=== useapi.net — universal note ===

Generated: 2026-05-20 04:11 UTC

Authentication (applies to every useapi.net API).
  Header: Authorization: Bearer user:<number>-<unique-string>
  Use the COMPLETE token, including the `user:` prefix and the alphanumeric
  suffix. Do not truncate. Do not URL-encode. A single token authorizes every
  API under the user's subscription.

Service-specific patterns. Identifier names (jobid / taskId / musicId / etc.),
job lifecycle, response shapes, webhook semantics, and synchronous-vs-async
behavior vary PER API. Use ONLY the service-specific documentation below to
determine the correct request body, response shape, polling endpoint, and
status values for THIS API. Do not assume conventions from another useapi.net
API carry over.

For cross-service context (e.g. which APIs expose the same underlying model,
billing tiers, model availability matrix), see https://useapi.net/llms.txt

=== END universal note ===
useapi.net — Experimental API for AI services. $15/month subscription gives full access to all APIs listed below.
Subscribe: https://useapi.net/docs/subscription
Support: https://discord.gg/w28uK3cnmF | https://t.me/use_api

=== URL: https://useapi.net/docs/start-here/setup-dreamina ===
Document URL: https://useapi.net/docs/start-here/setup-dreamina
# <img src="/assets/images/dreamina-logo.png" style="height:1em;vertical-align: middle;"> Dreamina
<small>February 23, 2026 (April 17, 2026)</small>

## Table of contents
<small>Approximately 10 minutes to complete setup steps.</small>

---
> This is the setup guide for [Dreamina API](/docs/api-dreamina-v1). An active [Dreamina](https://dreamina.capcut.com/) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work.

[Dreamina](https://dreamina.capcut.com/) creates AI-generated videos and images using models from [ByteDance's Seed](https://seed.bytedance.com/) family.

The API supports two regions: **US** and **CA** (Canada). Both expose `seedance-2.0` and `seedance-2.0-fast` at 720p and share the same image models. 1080p Seedance 2.0 is CA-only for now — will change once Dreamina adds US support.

CA is ~3× cheaper per second for the same Seedance 2.0 models — see the [Cost calculator](#cost-calculator) below.

### VPN setup

A VPN with a US or Canadian IP address is required to create a Dreamina account. The VPN is only needed for browser-based account creation — the API handles all requests through its own proxy infrastructure.

**For US region accounts:**

[Opera](https://www.opera.com/) browser has a built-in free VPN.

1. Download and install [Opera](https://www.opera.com/) if you don't have it already
2. Enable the built-in VPN by clicking the **VPN** badge in the address bar
3. Set the VPN region to **Americas**
4. Verify the VPN is active — you should see "Protected" and an Americas IP address

![](/assets/images/setup-dreamina-1.jpg)

**For CA region accounts:**

Opera's free VPN does not support the Canadian region. You will need a commercial VPN service that offers Canadian server locations (e.g., NordVPN, ExpressVPN, Surfshark, or similar). Set your VPN to a **Canada** server before creating the account.

### Create a Dreamina account

⚠️ **Use a dedicated email account for this API — do NOT use your personal email.**

1. Navigate to [https://dreamina.capcut.com/](https://dreamina.capcut.com/) with your VPN active and set to the desired region (Americas for US, Canada for CA)
2. Verify your region by checking the URL — US accounts will see `dreamina.capcut.com`, CA accounts may see a Canadian IP in the VPN indicator
3. Click **Sign in** in the bottom-left corner
4. Select **Continue with email** from the login options

![](/assets/images/setup-dreamina-2.jpg)

5. Click **Sign up** to create a new account
6. Enter your **email address** and choose a **password**
7. Click **Continue** to complete registration

![](/assets/images/setup-dreamina-3.jpg)

You may need to verify your email address by entering a code sent to your inbox.

### Verify available models

Before adding your account to the API, confirm that the desired Seedance models are available:

1. Navigate to [https://dreamina.capcut.com/ai-tool/generate](https://dreamina.capcut.com/ai-tool/generate)
2. Select **AI Video** from the mode selector at the bottom
3. Click the model name to open the model dropdown and verify that your desired models (e.g., Seedance 2.0 Fast, Seedance 2.0) are listed

![](/assets/images/setup-dreamina-5.jpg)

If you don't see Seedance 2.0 models, your account may have been created in the wrong region. Create a new account with the correct VPN region.

We recommend starting with the **Basic plan** to verify that subscription and generation work end-to-end before upgrading to the **Advanced plan**. The model dropdown is only an advertisement — Dreamina sometimes lists models that fail at execution for a given region or account. Running one successful generation on the Basic plan confirms the model actually works for your account before you commit to a larger plan.

### Verify and add account

Use the form below to verify your credentials and add your Dreamina account.

Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) directly.

<script>
  async function apiTestAccountDreamina(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-Dreamina-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let email = document.getElementById('post-accounts-Dreamina-email')?.value;
      let password = document.getElementById('post-accounts-Dreamina-password')?.value;

      let region = document.getElementById('post-accounts-Dreamina-region')?.value || 'CA';
      const body = { email, password, region };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute('https://api.useapi.net/v1/dreamina/accounts', 'post-accounts-Dreamina', data);
  }
</script>

<form id="post-accounts-Dreamina" onsubmit="apiTestAccountDreamina(document.getElementById('post-accounts-Dreamina-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Dreamina-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Dreamina-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Dreamina-email"><span>Dreamina email</span>
        <input id="post-accounts-Dreamina-email" type="text" class="input-element" required aria-required="true" placeholder="your-dreamina-email@example.com">
      </label>
      <label for="post-accounts-Dreamina-password"><span>Dreamina password</span>
        <input id="post-accounts-Dreamina-password" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="post-accounts-Dreamina-region"><span>region</span>
        <select id="post-accounts-Dreamina-region" class="input-element">
          <option value="CA">CA (Canada)</option>
          <option value="US">US</option>
        </select>
      </label>
      <label for="post-accounts-Dreamina-action"><span>action</span>
        <select id="post-accounts-Dreamina-action" class="input-element">
          <option value="verify">Verify — test credentials only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Dreamina-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-Dreamina-response" class="response-placeholder visible-false"></div>

### Cost calculator

**CA is ~3× cheaper per second** than US for the same Seedance 2.0 models.

| Model | US $/sec | CA $/sec |
|-------|---------:|---------:|
| Seedance 2.0 Fast | $0.113 | **$0.036** |
| Seedance 2.0 (720p) | $0.138 | **$0.044** |
| Seedance 2.0 (1080p) | — | **$0.108** |

Example — 10-second clip:

* Seedance 2.0 Fast: **$1.13 on US** vs **$0.36 on CA**
* Seedance 2.0 (720p): **$1.38 on US** vs **$0.43 on CA**

Plans compared — Advanced monthly (<a href="https://dreamina.capcut.com/pricing" target="_blank">see plans</a>):

* **US:** USD$70/mo, 8,645 credits
* **CA:** C$94.90/mo ≈ USD$68/mo, 37,070 credits (C$1 ≈ USD$0.72) → ~4.3× more credits per USD

1080p Seedance 2.0 is CA-only for now — will change once Dreamina adds US support. Consider [video upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) (720p → 1440p at 2×) as a cheaper alternative to native 1080p.

<details markdown="block">
<summary>Show the math</summary>

**Step 1 — credits per second** (from Dreamina's generation cost label, measured on a 4s clip):

| Model | US | CA |
|-------|-----|-----|
| Seedance 2.0 Fast | 56 cr / 4s = **14 cr/s** | 76 cr / 4s = **19 cr/s** |
| Seedance 2.0 (720p) | 68 cr / 4s = **17 cr/s** | 92 cr / 4s = **23 cr/s** |
| Seedance 2.0 (1080p) | n/a | 228 cr / 4s = **57 cr/s** |

**Step 2 — USD per credit** (Advanced plan pricing from the screenshots above):

| Region | Plan rate per 100 credits | USD per credit |
|--------|---------------------------|----------------|
| US | $0.81 | $0.81 / 100 = **$0.0081** |
| CA | C$0.26 × USD$0.72/C$1 = USD$0.187 | USD$0.187 / 100 = **$0.0019** |

**Step 3 — USD per second** = credits/sec × USD/credit:

| Model | US calc | CA calc |
|-------|---------|---------|
| Seedance 2.0 Fast | 14 × $0.0081 = **$0.113/s** | 19 × $0.0019 = **$0.036/s** |
| Seedance 2.0 (720p) | 17 × $0.0081 = **$0.138/s** | 23 × $0.0019 = **$0.044/s** |
| Seedance 2.0 (1080p) | — | 57 × $0.0019 = **$0.108/s** |

**Why CA is ~3× cheaper even though it gives 4.3× more credits per USD:** CA burns ~1.35× more credits per second for the same model (19 vs 14, 23 vs 17). Net: `4.3 ÷ 1.35 ≈ 3.2×` cheaper per second in USD.

</details>

<details markdown="block">
<summary>Plan screenshots</summary>

![](/assets/images/setup-dreamina-6-us.jpg)
<small>US Advanced — US Dollars ($)</small>

![](/assets/images/setup-dreamina-6.jpg)
<small>CA Advanced — Canadian Dollars (C$)</small>

</details>

### Important notes

- **First generation via browser** — after setting up your account, generate at least one video using the Dreamina website (e.g., a short Seedance 2.0 Fast clip in Omni Reference mode) to ensure the service is working and to accept the Terms of Service. This is a one-time step before using the API.
- **VPN not required for API usage** — the VPN is only needed for creating the Dreamina account in the browser. The API handles all requests through its own proxy infrastructure.
- **Region is permanent** — use the same region for the account as the VPN used during creation. US accounts must use `region: "US"`, Canadian accounts must use `region: "CA"`.
- **Session management** — the API automatically manages your Dreamina session, including refreshing expired sessions. If you see `596` errors, re-add your account via [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts).
- **Avoid using the same account** simultaneously through both the API and the Dreamina website — it should work, but to play safe it's better to avoid potential session conflicts.
- **Avoid logging in from other regions** — do not log in to your Dreamina account from any region other than the one used during creation, as it may change the account's default region.
- **Free credits** — new Dreamina accounts receive free credits. Check your balance via [GET /accounts/`account`](/docs/api-dreamina-v1/get-dreamina-accounts-account).

=== URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-accounts-account ===
Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-accounts-account
## Delete Account Configuration
<small>February 23, 2026</small>

---

Delete a configured Dreamina account. This removes the account from your configuration and cleans up any executing job entries.

**Warning:** This action cannot be undone. You will need to reconfigure the account using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) if you want to use it again.
> **https://api.useapi.net/v1/dreamina/accounts/`account`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `account` is **required**.

### Responses

**200**
**200 OK**

Account deleted successfully.

```json
{
  "account": "US:user@example.com",
  "deleted": true,
  "remaining": 0
}
```

- `remaining` - Number of other accounts still configured.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for account US:user@example.com"
}
```

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/accounts/US:user@example.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const account = 'US:user@example.com';

const response = await fetch(
  `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(account)}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const result = await response.json();
console.log('Delete result:', result);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
account = 'US:user@example.com'

headers = {'Authorization': f'Bearer {token}'}

response = requests.delete(
    f'https://api.useapi.net/v1/dreamina/accounts/{quote(account, safe="")}',
    headers=headers
)

print('Delete result:', response.json())
```

### Try It

<script>
  async function apiExecuteDeleteDreaminaAccountsAccount() {
    const tokenElement = document.getElementById('input-token');
    const accountElement = document.getElementById('input-account');

    const data = {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(accountElement.value)}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (required)</small></span>
        <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaAccountsAccount()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-assets-assetid ===
Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-assets-assetid
## Delete Asset
<small>March 2, 2026</small>

---

Delete a specific asset (image or video) from generation history. The `assetId` is obtained from [GET /assets/`account`](/docs/api-dreamina-v1/get-dreamina-assets-account), completed [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid), or [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) results.
> **https://api.useapi.net/v1/dreamina/assets/`assetId`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `assetId` is **required**.

### Responses

**200**
**200 OK**

Asset deleted successfully.

```json
{
  "deleted": true,
  "assetId": "US:user@example.com-306191111942:7612453183683579150",
  "account": "US:user@example.com"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for account US:user@example.com"
}
```

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/assets/US:user@example.com-306191111942:7612453183683579150"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const assetId = 'US:user@example.com-306191111942:7612453183683579150';

const response = await fetch(
  `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(assetId)}`,
  {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` }
  }
);

const result = await response.json();
console.log('Delete result:', result);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
asset_id = 'US:user@example.com-306191111942:7612453183683579150'

response = requests.delete(
    f'https://api.useapi.net/v1/dreamina/assets/{quote(asset_id, safe="")}',
    headers={'Authorization': f'Bearer {token}'}
)

print('Delete result:', response.json())
```

### Try It

<script>
  async function apiExecuteDeleteDreaminaAssetsAssetId() {
    const tokenElement = document.getElementById('input-token');
    const assetIdElement = document.getElementById('input-assetid');

    const data = {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(assetIdElement.value)}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-assetid"><span>assetId<small> (required, from <a href="/docs/api-dreamina-v1/get-dreamina-assets-account">GET /assets/account</a>)</small></span>
        <input id="input-assetid" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com-306191111942:7612453183683579150">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaAssetsAssetId()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-scheduler-jobid ===
Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-scheduler-jobid
## Cancel Executing Job
<small>February 23, 2026</small>

---

Remove a job from the executing tracker and cancel it. If the job is still in `created` status, it will be marked as failed with the reason "Cancelled by user".
> **https://api.useapi.net/v1/dreamina/scheduler/`jobid`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobid` is **required**. The job ID to remove from the scheduler.

### Responses

**200**
**200 OK**

Job removed from scheduler.

```json
{
  "jobid": "j0223140530123456789v-u12345-US:user@example.com-bot:dreamina",
  "removed": true
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Job belongs to a different user.

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/scheduler/j0223140530123456789v-u12345-US:user@example.com-bot:dreamina"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const jobid = 'j0223140530123456789v-u12345-US:user@example.com-bot:dreamina';

const response = await fetch(
  `https://api.useapi.net/v1/dreamina/scheduler/${jobid}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const result = await response.json();
console.log('Cancel result:', result);
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
jobid = 'j0223140530123456789v-u12345-US:user@example.com-bot:dreamina'

headers = {'Authorization': f'Bearer {token}'}

response = requests.delete(
    f'https://api.useapi.net/v1/dreamina/scheduler/{jobid}',
    headers=headers
)

print('Cancel result:', response.json())
```

### Try It

<script>
  async function apiExecuteDeleteDreaminaSchedulerJobId() {
    const tokenElement = document.getElementById('input-token');
    const jobidElement = document.getElementById('input-jobid');

    const data = {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/scheduler/${jobidElement.value}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required)</small></span>
        <input id="input-jobid" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaSchedulerJobId()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts-account ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts-account
## Get Account Configuration
<small>February 23, 2026 (March 2, 2026)</small>

---

Get configuration details for a specific Dreamina account, including session status, available models, and credit balance. Can also be called once a day to claim free daily credits.
> **https://api.useapi.net/v1/dreamina/accounts/`account`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `account` is **required**.

### Responses

**200**
**200 OK**

Account details retrieved with live data from upstream.

```json
{
  "account": "US:user@example.com",
  "email": "user@example.com",
  "region": "US",
  "maxJobs": 10,
  "sessionExpires": "2026-04-24T12:00:00.000Z",
  "session": {
    "expires": "2026-04-24T12:00:00.000Z",
    "lastRefreshed": "2026-02-23T12:00:00.000Z",
    "daysUntilExpiry": 60
  },
  "models": {
    "video": ["seedance-2.0", "seedance-1.5-pro", "seedance-1.0-mini"],
    "image": ["seedream-4.5", "seedream-4.1", "seedream-4.0", "nano-banana", "seedream-3.0"]
  },
  "credits": {
    "total": 24065,
    "vip": 12000,
    "gift": 10065,
    "purchase": 2000,
    "dailyClaimed": true
  }
}
```

**Note:** The `models`, `credits`, and `session` fields are fetched live from upstream. If upstream queries fail, a summary without these fields is returned.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for account US:user@example.com"
}
```

### Model
```typescript
{
  account: string                // "US:user@example.com"
  email: string
  region: string                 // "US"
  maxJobs: number                // 1-50
  sessionExpires: string         // ISO 8601 timestamp
  session?: {
    expires: string              // ISO 8601 timestamp
    lastRefreshed: string        // ISO 8601 timestamp
    daysUntilExpiry: number
  }
  models?: {
    video: string[]              // Available video model names
    image: string[]              // Available image model names
  }
  credits?: {
    total: number
    vip: number
    gift: number
    purchase: number
    dailyClaimed: boolean
  }
  error?: string                 // Error message
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/accounts/US:user@example.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const account = 'US:user@example.com';

const response = await fetch(
  `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(account)}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const accountConfig = await response.json();
console.log('Account:', accountConfig);
console.log('Credits:', accountConfig.credits);
console.log('Models:', accountConfig.models);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
account = 'US:user@example.com'

headers = {'Authorization': f'Bearer {token}'}

response = requests.get(
    f'https://api.useapi.net/v1/dreamina/accounts/{quote(account, safe="")}',
    headers=headers
)

account_config = response.json()
print('Account:', account_config)
print('Credits:', account_config.get('credits'))
print('Models:', account_config.get('models'))
```

### Try It

<script>
  async function apiExecuteGetDreaminaAccountsAccount() {
    const tokenElement = document.getElementById('input-token');
    const accountElement = document.getElementById('input-account');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(accountElement.value)}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (required)</small></span>
        <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAccountsAccount()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts
## List All Configured Accounts
<small>February 23, 2026</small>

---

List all configured Dreamina accounts.

To get a specific account with live details use [GET /accounts/`account`](/docs/api-dreamina-v1/get-dreamina-accounts-account).
> **https://api.useapi.net/v1/dreamina/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

Returns a map of all configured accounts, keyed by account identifier.

```json
{
  "US:user@example.com": {
    "account": "US:user@example.com",
    "email": "user@example.com",
    "region": "US",
    "maxJobs": 10,
    "sessionExpires": "2026-04-24T12:00:00.000Z"
  }
}
```

If no accounts are configured, returns an empty object `{}`.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model
```typescript
// Map of account identifier to account summary
{
  [account: string]: {
    account: string              // "US:user@example.com"
    email: string
    region: string               // "US"
    maxJobs: number
    sessionExpires: string       // ISO 8601 timestamp
    error?: string               // Error message if account has issues
  }
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/accounts"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/dreamina/accounts', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const accounts = await response.json();
console.log('Configured accounts:', accounts);
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {'Authorization': f'Bearer {token}'}

response = requests.get('https://api.useapi.net/v1/dreamina/accounts', headers=headers)
print('All accounts:', response.json())
```

### Try It

<script>
  async function apiExecuteGetDreaminaAccounts() {
    const tokenElement = document.getElementById('input-token');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/accounts', 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAccounts()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-assets-account ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-assets-account
## List Generation History
<small>March 2, 2026</small>

---

List generation history (images and videos) for a specific account. Returns assets with their URLs, dimensions, and reusable `assetRef` values for [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or as in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos).
> **https://api.useapi.net/v1/dreamina/assets/`account`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `account` is **required**.

### Query Parameters

- `count` is optional. Number of assets to return (1-100, default: `20`).
- `offset` is optional. Pagination cursor from a previous response's `nextOffset`.

### Responses

**200**
**200 OK**

Returns generation history with asset details.

```json
{
  "assets": [
    {
      "assetId": "US:user@example.com-306191111942:7612453183683579150",
      "historyRecordId": "306191111942",
      "itemId": "7612453183683579150",
      "type": "image",
      "coverUrl": "https://p9-sign.douyinpic.com/...",
      "description": "A stunning aurora borealis over a frozen lake",
      "assetRef": "US:user@example.com-image:w2560:h1440:s905000-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
      "imageUrl": "https://p9-sign.douyinpic.com/...",
      "width": 2560,
      "height": 1440,
      "format": "webp",
      "createdAt": "2026-03-02T14:06:06.000Z"
    },
    {
      "assetId": "US:user@example.com-306191137798:7612453244173880589",
      "historyRecordId": "306191137798",
      "itemId": "7612453244173880589",
      "type": "video",
      "coverUrl": "https://p9-sign.douyinpic.com/...",
      "description": "A cinematic drone shot",
      "videoUrl": "https://v16m-default.akamaized.net/...",
      "width": 1280,
      "height": 720,
      "createdAt": "2026-03-02T14:08:07.000Z"
    }
  ],
  "hasMore": true,
  "nextOffset": 20,
  "account": "US:user@example.com"
}
```

- `assetRef` on image assets can be used directly as `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or as `firstFrameRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos).
- `assetId` can be used with [DELETE /assets/`assetId`](/docs/api-dreamina-v1/delete-dreamina-assets-assetid) to remove an asset.
- Videos do not have `assetRef` — only a `videoUrl` for download.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for account US:user@example.com"
}
```

### Model
```typescript
{
  assets: Array<{
    assetId: string              // ID for DELETE /assets/<assetId>
    historyRecordId: string
    itemId: string
    type: 'image' | 'video'
    coverUrl?: string            // Thumbnail URL
    description?: string         // Generation prompt
    assetRef?: string            // Reusable ref (images only)
    imageUrl?: string            // Full image URL (images only)
    videoUrl?: string            // Video URL (videos only)
    width?: number
    height?: number
    format?: string              // Image format (images only)
    createdAt?: string           // ISO 8601 timestamp
  }>
  hasMore: boolean               // More pages available
  nextOffset: number             // Pass as offset for next page
  account: string
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/assets/US:user@example.com?count=10"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const account = 'US:user@example.com';

const response = await fetch(
  `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(account)}?count=20`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);

const result = await response.json();
console.log(`Assets: ${result.assets.length}, hasMore: ${result.hasMore}`);

result.assets.forEach(a => {
  console.log(`  ${a.type} ${a.assetId} ${a.width}x${a.height}`);
  if (a.assetRef) console.log(`    assetRef: ${a.assetRef}`);
});
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
account = 'US:user@example.com'

response = requests.get(
    f'https://api.useapi.net/v1/dreamina/assets/{quote(account, safe="")}',
    headers={'Authorization': f'Bearer {token}'},
    params={'count': 20}
)

result = response.json()
print(f"Assets: {len(result['assets'])}, hasMore: {result['hasMore']}")

for a in result['assets']:
    print(f"  {a['type']} {a['assetId']} {a.get('width')}x{a.get('height')}")
```

### Try It

<script>
  async function apiExecuteGetDreaminaAssetsAccount() {
    const tokenElement = document.getElementById('input-token');
    const accountElement = document.getElementById('input-account');
    const countValue = document.getElementById('input-count')?.value;
    const offsetValue = document.getElementById('input-offset')?.value;

    const params = new URLSearchParams();
    if (countValue) params.set('count', countValue);
    if (offsetValue) params.set('offset', offsetValue);

    const qs = params.toString();

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(accountElement.value)}${qs ? '?' + qs : ''}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (required)</small></span>
        <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com">
      </label>
      <label for="input-count"><span>count<small> (1-100, default: 20)</small></span>
        <input id="input-count" type="number" class="input-element" min="1" max="100" placeholder="20">
      </label>
      <label for="input-offset"><span>offset<small> (pagination cursor)</small></span>
        <input id="input-offset" type="number" class="input-element" placeholder="0">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAssetsAccount()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-images-jobid ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-images-jobid
## Retrieve Image Job Status
<small>March 2, 2026</small>

---

Retrieve the status and result of an image generation or upscale job by its job ID.

Use this endpoint to poll for completion after submitting an image via [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale). Jobs are retained for 30 days.
> **https://api.useapi.net/v1/dreamina/images/`jobid`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobid` is **required**, the unique job identifier returned from [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale).

### Responses

**200**
**200 OK**

Returns the job record with current status and details.

**Processing (status: created):**

```json
{
  "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
  "type": "image",
  "status": "created",
  "model": "seedream-4.0",
  "created": "2026-03-02T14:05:30.123Z",
  "request": {
    "prompt": "A stunning aurora borealis over a frozen lake",
    "model": "seedream-4.0",
    "ratio": "16:9",
    "resolution": "2k",
    "inputMode": "generate"
  },
  "response": {
    "forecastCost": 0
  },
  "code": 200
}
```

**Completed (image generation):**

```json
{
  "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
  "type": "image",
  "status": "completed",
  "model": "seedream-4.0",
  "created": "2026-03-02T14:05:30.123Z",
  "updated": "2026-03-02T14:06:06.789Z",
  "request": {
    "prompt": "A stunning aurora borealis over a frozen lake",
    "model": "seedream-4.0",
    "ratio": "16:9",
    "resolution": "2k",
    "inputMode": "generate"
  },
  "response": {
    "images": [
      {
        "imageUrl": "https://p9-sign.douyinpic.com/...",
        "imageUri": "tos-useast5-i-wopfjsm1ax-tx/abc123",
        "width": 2560,
        "height": 1440,
        "format": "jpeg",
        "assetId": "US:user@example.com-306191111942:7612453183683579150",
        "assetRef": "US:user@example.com-image:w2560:h1440:s905000-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
        "itemId": "7612453183683579150"
      },
      {
        "imageUrl": "https://p9-sign.douyinpic.com/...",
        "imageUri": "tos-useast5-i-wopfjsm1ax-tx/def456",
        "width": 2560,
        "height": 1440,
        "format": "jpeg",
        "assetId": "US:user@example.com-306191111942:7612453183683595534",
        "assetRef": "US:user@example.com-image:w2560:h1440:s911000-uri:tos-useast5-i-wopfjsm1ax-tx/def456",
        "itemId": "7612453183683595534"
      }
    ],
    "forecastCost": 0,
    "historyRecordId": "306191111942",
    "finishTime": 1709391966
  },
  "code": 200
}
```

**Completed (upscale):**

```json
{
  "jobid": "j0302140630123456789I-u12345-US:user@example.com-bot:dreamina",
  "type": "upscale",
  "status": "completed",
  "model": "seedream-4.0",
  "created": "2026-03-02T14:06:30.123Z",
  "updated": "2026-03-02T14:08:07.456Z",
  "request": {
    "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
    "imageIndex": 0,
    "resolution": "4k"
  },
  "response": {
    "images": [
      {
        "imageUrl": "https://p9-sign.douyinpic.com/...",
        "imageUri": "tos-useast5-i-wopfjsm1ax-tx/upscaled123",
        "width": 4096,
        "height": 4096,
        "format": "jpeg",
        "assetId": "US:user@example.com-306191137798:7612453244173880589",
        "assetRef": "US:user@example.com-image:w4096:h4096:s1482000-uri:tos-useast5-i-wopfjsm1ax-tx/upscaled123",
        "itemId": "7612453244173880589"
      }
    ],
    "forecastCost": 0,
    "historyRecordId": "306191137798",
    "finishTime": 1709392087
  },
  "code": 200
}
```

**Note:** The `assetRef` on each image can be used directly as `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images) for further generations, without needing to re-upload.

**Failed:**

```json
{
  "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
  "type": "image",
  "status": "failed",
  "model": "seedream-4.0",
  "created": "2026-03-02T14:05:30.123Z",
  "updated": "2026-03-02T14:07:15.456Z",
  "request": {
    "prompt": "A test prompt",
    "model": "seedream-4.0",
    "ratio": "16:9",
    "resolution": "2k",
    "inputMode": "generate"
  },
  "error": "fail_code: 2038",
  "errorDetails": "ContentFiltered",
  "code": 2038
}
```

**Note:** Jobs older than 1 hour that are still `created` are auto-marked as failed with `"Generation timed out"` (code `408`).

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Job not found, belongs to a different user, or has expired (>30 days).

```json
{
  "error": "Job not found"
}
```

### Model

**Completed**

Image generation completed. Includes image URLs and metadata.

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'image' | 'upscale'       // Job type
  status: 'completed'
  model: string                    // Model used
  created: string                  // ISO 8601 timestamp
  updated: string                  // ISO 8601 timestamp

  request: {
    prompt?: string
    model?: string
    ratio?: string
    resolution?: string
    inputMode?: string             // Auto-detected from params
    imageRef_1?: string            // Reference image assetRef (when provided)
    imageRef_2?: string
    imageRef_3?: string
    jobid?: string                 // Source job (upscale only)
    imageIndex?: number            // Source image index (upscale only)
    replyUrl?: string
    replyRef?: string
  }

  response: {
    images: Array<{
      imageUrl: string             // Direct image URL (JPEG)
      imageUri: string             // Native URI
      width: number                // Image width in pixels
      height: number               // Image height in pixels
      format: string               // "jpeg"
      assetId: string              // Asset identifier
      assetRef: string             // Can be used as imageRef_N in POST /images
      itemId: string               // Upstream item ID
    }>
    forecastCost: number           // Credit cost
    historyRecordId: string        // Upstream history record
    finishTime: number             // Unix timestamp of completion
  }

  code: number                     // 200
}
```

**Failed**

Image generation failed. Includes error details.

```typescript
{
  jobid: string
  type: 'image' | 'upscale'
  status: 'failed'
  model: string
  created: string
  updated: string

  request: {
    prompt?: string
    model?: string
    ratio?: string
    resolution?: string
    inputMode?: string
    replyUrl?: string
    replyRef?: string
  }

  error: string                    // Error summary
  errorDetails?: string            // Additional details
  code: number                     // Error code
}
```

**Common error codes:**

| Code | Meaning |
|------|---------|
| 408 | Generation timed out (>1 hour) |
| 596 | Account session expired |
| 2038 | Content filtered |
| 2057 | Upstream processing error |

### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/dreamina/images/j0302140530123456789i-u12345-US:user@example.com-bot:dreamina" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**JavaScript**
```javascript
const apiToken = 'YOUR_API_TOKEN'
const jobId = 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina'

async function waitForImages(jobId, intervalMs = 10000) {
  while (true) {
    const response = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobId}`, {
      headers: { 'Authorization': `Bearer ${apiToken}` }
    })
    const job = await response.json()
    console.log(`Status: ${job.status}`)

    if (job.status === 'completed') {
      job.response.images.forEach((img, i) =>
        console.log(`  [${i}] ${img.width}x${img.height} ${img.format}`)
      )
      return job
    }

    if (job.status === 'failed') throw new Error(job.error)

    await new Promise(resolve => setTimeout(resolve, intervalMs))
  }
}

const job = await waitForImages(jobId)
```

**Python**
```python
import requests
import time

api_token = 'YOUR_API_TOKEN'
job_id = 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina'

def wait_for_images(job_id: str, interval_sec: int = 10) -> dict:
    while True:
        job = requests.get(
            f'https://api.useapi.net/v1/dreamina/images/{job_id}',
            headers={'Authorization': f'Bearer {api_token}'}
        ).json()
        print(f"Status: {job['status']}")

        if job['status'] == 'completed':
            for i, img in enumerate(job['response']['images']):
                print(f"  [{i}] {img['width']}x{img['height']} {img['format']}")

                # Download image
                img_response = requests.get(img['imageUrl'])
                with open(f'image_{i}.jpeg', 'wb') as f:
                    f.write(img_response.content)
            return job

        if job['status'] == 'failed':
            raise Exception(f"Job failed: {job.get('error')}")

        time.sleep(interval_sec)

job = wait_for_images(job_id)
```

### Try It

<script>
  function displayDreaminaImageMedia(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (response.status === 'completed' && response.response?.images) {
      const images = response.response.images;

      if (images.length > 0) {
        const linksHTML = images.map((img, i) =>
          `<a href="${img.imageUrl}" target="_blank" rel="noopener noreferrer" class="media-link image">Image ${i + 1} (${img.width}x${img.height})</a>`
        ).join(' ');

        const typeLabel = response.type === 'upscale' ? 'Upscaled Image' : 'Generated Images';
        mediaContainer.innerHTML = `<div class="media-links-container"><strong>${typeLabel}:</strong> ${linksHTML}</div>`;
        mediaContainer.style.display = 'block';
        return;
      }
    }

    mediaContainer.style.display = 'none';
  }

  async function apiExecuteGetDreaminaImagesJobId() {
    const tokenElement = document.getElementById('input-token');
    const jobidElement = document.getElementById('input-jobid');
    const elementId = 'input';

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute(
      `https://api.useapi.net/v1/dreamina/images/${jobidElement.value}`,
      elementId,
      data
    );

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayDreaminaImageMedia(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for media display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required)</small></span>
        <input id="input-jobid" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaImagesJobId()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-scheduler ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-scheduler
## List Executing Jobs
<small>February 23, 2026 (March 2, 2026)</small>

---

List all currently executing (in-progress) video and image generation jobs, grouped by account.
> **https://api.useapi.net/v1/dreamina/scheduler**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

Returns executing jobs grouped by account.

```json
{
  "executing": {
    "US:user@example.com": [
      {
        "jobid": "j0223140530123456789v-u12345-US:user@example.com-bot:dreamina",
        "submitId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "model": "seedance-2.0",
        "elapsedSeconds": 45,
        "replyUrl": "https://your-domain.com/webhook"
      }
    ]
  },
  "total": 1
}
```

When no jobs are executing:

```json
{
  "executing": {},
  "total": 0
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model
```typescript
{
  executing: {
    [account: string]: Array<{
      jobid: string              // Job identifier
      submitId: string           // Upstream submission ID
      model: string              // Model used
      elapsedSeconds: number     // Seconds since job was submitted
      replyUrl?: string          // Webhook URL if configured
    }>
  }
  total: number                  // Total number of executing jobs
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/scheduler"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/dreamina/scheduler', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const scheduler = await response.json();
console.log('Executing jobs:', scheduler.total);
for (const [account, jobs] of Object.entries(scheduler.executing)) {
  console.log(`  ${account}: ${jobs.length} jobs`);
}
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {'Authorization': f'Bearer {token}'}

response = requests.get('https://api.useapi.net/v1/dreamina/scheduler', headers=headers)
scheduler = response.json()

print(f"Executing jobs: {scheduler['total']}")
for account, jobs in scheduler['executing'].items():
    print(f"  {account}: {len(jobs)} jobs")
```

### Try It

<script>
  async function apiExecuteGetDreaminaScheduler() {
    const tokenElement = document.getElementById('input-token');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/scheduler', 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaScheduler()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid ===
Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid
## Retrieve Job Status
<small>March 2, 2026 (April 14, 2026)</small>

---

Retrieve the status and result of a video generation, upscale, or interpolation job by its job ID.

Use this endpoint to poll for completion after submitting a video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), or [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Jobs are retained for 30 days.
> **https://api.useapi.net/v1/dreamina/videos/`jobid`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobid` is **required**, the unique job identifier returned from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), or [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate).

### Responses

**200**
**200 OK**

Returns the job record with current status and details.

**Processing (status: created):**

```json
{
  "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina",
  "type": "video",
  "status": "created",
  "model": "seedance-2.0",
  "created": "2026-02-23T14:05:30.123Z",
  "request": {
    "prompt": "A serene mountain landscape at sunset",
    "model": "seedance-2.0",
    "ratio": "16:9",
    "duration": 5,
    "inputMode": "prompt"
  },
  "response": {
    "forecastCost": 125
  },
  "code": 200
}
```

**Completed:**

```json
{
  "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina",
  "type": "video",
  "status": "completed",
  "model": "seedance-2.0",
  "created": "2026-02-23T14:05:30.123Z",
  "updated": "2026-02-23T14:07:15.456Z",
  "request": {
    "prompt": "A serene mountain landscape at sunset",
    "model": "seedance-2.0",
    "ratio": "16:9",
    "duration": 5,
    "inputMode": "prompt"
  },
  "response": {
    "assetId": "CA:user@example.com-306191137798:7341234567890123456",
    "videoUrl": "https://v16m-default.tiktokcdn.com/...",
    "videoUrlBackup": "https://v16m.byteicdn.com/...",
    "videoUrlWatermarked": "https://v16-cc.capcut.com/...",
    "watermarked": false,
    "videoId": "7341234567890123456",
    "coverUrl": "https://p9-sign.douyinpic.com/...",
    "width": 1280,
    "height": 720,
    "durationMs": 5042,
    "hasAudio": false,
    "forecastCost": 125,
    "finishTime": 1708700835
  },
  "code": 200
}
```

**Failed:**

```json
{
  "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina",
  "type": "video",
  "status": "failed",
  "model": "seedance-2.0",
  "created": "2026-02-23T14:05:30.123Z",
  "updated": "2026-02-23T14:07:15.456Z",
  "request": {
    "prompt": "A test prompt",
    "model": "seedance-2.0",
    "ratio": "16:9",
    "duration": 5,
    "inputMode": "prompt"
  },
  "error": "fail_code: 2043",
  "errorDetails": "OutputVideoRisk",
  "code": 2043
}
```

**Note:** Jobs older than 1 hour that are still `created` are auto-marked as failed with `"Generation timed out"` (code `408`).

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Job not found, belongs to a different user, or has expired (>30 days).

```json
{
  "error": "Job not found"
}
```

### Model

**Completed**

Video generation completed. Includes video URL and metadata.

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'video' | 'video-upscale' | 'video-interpolate'  // Job type
  status: 'completed'
  model: string                    // Model used
  created: string                  // ISO 8601 timestamp
  updated: string                  // ISO 8601 timestamp

  request: {
    prompt?: string
    model: string
    ratio?: string
    duration?: number
    inputMode: string              // "prompt" | "first_frame" | "end_frame" | "multi_frame" | "unified_edit"
    resolution?: string            // "720p" or "1080p"
    firstFrameRef?: string
    endFrameRef?: string
    frame_1_imageRef?: string      // Keyframe refs (multi_frame mode)
    frame_1_prompt?: string
    frame_1_duration?: number
    frame_2_imageRef?: string
    frame_2_prompt?: string
    frame_2_duration?: number
    replyUrl?: string
    replyRef?: string
  }

  response: {
    assetId: string                // For DELETE /assets/<assetId>
    videoUrl: string               // Direct MP4 URL — clean (non-watermarked) master when available; falls back to the watermarked variant for models that don't expose a master
    videoUrlBackup?: string        // Alternate CDN host for the same master (use if primary fails)
    videoUrlBackups?: string[]     // Full list of alternate master URLs when more than one is provided
    videoUrlWatermarked?: string   // Watermarked variant, preserved as a fallback and for compliance/traceability of AI-generated content
    watermarked?: boolean          // true when the returned videoUrl carries Dreamina's AIGC transparency badge
    videoId: string                // Dreamina video ID
    coverUrl: string               // Video cover/thumbnail URL
    width: number                  // Video width in pixels
    height: number                 // Video height in pixels
    durationMs: number             // Video duration in milliseconds
    hasAudio: boolean              // Whether video has audio
    forecastCost: number           // Credit cost
    finishTime: number             // Unix timestamp of completion
    upscaleJobid?: string          // Set after POST /videos/upscale
  }

  code: number                     // 200
}
```

#### Watermark handling

Dreamina's backend renders every generated video twice:

- A **clean master** served from `v16m-default.tiktokcdn.com` / `v16m.byteicdn.com`.
- A **watermarked transcode** served from `v16-cc.capcut.com` with a baked-in top-left "AI" transparency badge and (on non-premium accounts) a bottom-right Dreamina brand mark.

`GET /videos/<jobid>` returns the clean master as `videoUrl` whenever the upstream response exposes one, and keeps the watermarked URL in `videoUrlWatermarked` as a fallback. The `watermarked` flag reflects which variant `videoUrl` is currently pointing at.

For models that don't expose a master (e.g. Sora 2), `videoUrl` falls back to the watermarked variant and `watermarked` becomes `true`. The watermark is baked into the MP4 at render time — there is no URL parameter that strips it from the watermarked variant, and attempting to edit the URL invalidates its signature.

All video URLs are signed and expire ~7 days after generation. Download promptly.

**Failed**

Video generation failed. Includes error details.

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'video' | 'video-upscale' | 'video-interpolate'
  status: 'failed'
  model: string
  created: string                  // ISO 8601 timestamp
  updated: string                  // ISO 8601 timestamp

  request: {
    prompt?: string
    model: string
    ratio?: string
    duration?: number
    inputMode: string
    firstFrameRef?: string
    endFrameRef?: string
    replyUrl?: string
    replyRef?: string
  }

  error: string                    // Error summary (e.g., "fail_code: 2043")
  errorDetails?: string            // Additional details (e.g., "OutputVideoRisk")
  code: number                     // Error code (e.g., 2043, 408, 596)
}
```

**Common error codes:**

| Code | Meaning |
|------|---------|
| 408 | Generation timed out (>1 hour) |
| 596 | Account session expired |
| 2038 | Content filtered |
| 2043 | Output video moderation risk |

### Examples

**Curl**
```bash
# Get job status
curl "https://api.useapi.net/v1/dreamina/videos/j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Poll for completion (check every 10 seconds)
while true; do
  RESULT=$(curl -s "https://api.useapi.net/v1/dreamina/videos/$JOBID" \
    -H "Authorization: Bearer YOUR_API_TOKEN")

  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "Status: $STATUS"

  if [[ "$STATUS" == "completed" ]]; then
    echo "$RESULT" | jq -r '.response.videoUrl'
    break
  fi

  if [[ "$STATUS" == "failed" ]]; then
    echo "$RESULT" | jq -r '.error'
    break
  fi

  sleep 10
done
```

**JavaScript**
```javascript
const apiToken = 'YOUR_API_TOKEN'
const jobId = 'j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina'

async function getJobStatus(jobId) {
  const response = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobId}`, {
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  })
  return await response.json()
}

// Poll until completion
async function waitForCompletion(jobId, intervalMs = 10000) {
  while (true) {
    const job = await getJobStatus(jobId)
    console.log(`Status: ${job.status}`)

    if (job.status === 'completed') {
      console.log('Video URL:', job.response.videoUrl)
      console.log('Dimensions:', `${job.response.width}x${job.response.height}`)
      console.log('Duration:', `${job.response.durationMs}ms`)
      return job
    }

    if (job.status === 'failed') {
      console.error('Job failed:', job.error)
      throw new Error(job.error)
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs))
  }
}

const job = await waitForCompletion(jobId)
```

**Python**
```python
import requests
import time

api_token = 'YOUR_API_TOKEN'
job_id = 'j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina'

def get_job_status(job_id: str) -> dict:
    response = requests.get(
        f'https://api.useapi.net/v1/dreamina/videos/{job_id}',
        headers={'Authorization': f'Bearer {api_token}'}
    )
    response.raise_for_status()
    return response.json()

def wait_for_completion(job_id: str, interval_sec: int = 10) -> dict:
    while True:
        job = get_job_status(job_id)
        print(f"Status: {job['status']}")

        if job['status'] == 'completed':
            print(f"Video URL: {job['response']['videoUrl']}")
            print(f"Dimensions: {job['response']['width']}x{job['response']['height']}")

            # Download video
            video_response = requests.get(job['response']['videoUrl'])
            with open('output.mp4', 'wb') as f:
                f.write(video_response.content)
            print('Video saved to output.mp4')
            return job

        if job['status'] == 'failed':
            raise Exception(f"Job failed: {job.get('error')}")

        time.sleep(interval_sec)

job = wait_for_completion(job_id)
```

### Try It

<script>
  function displayDreaminaVideoMedia(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (response.status === 'completed' && response.response?.videoUrl) {
      const r = response.response;
      const label = `Video (${r.width}x${r.height}, ${r.durationMs}ms)`;
      mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Video:</strong> <a href="${r.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${label}</a></div>`;
      mediaContainer.style.display = 'block';
      return;
    }

    mediaContainer.style.display = 'none';
  }

  async function apiExecuteGetDreaminaVideosJobId() {
    const tokenElement = document.getElementById('input-token');
    const jobidElement = document.getElementById('input-jobid');
    const elementId = 'input';

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute(
      `https://api.useapi.net/v1/dreamina/videos/${jobidElement.value}`,
      elementId,
      data
    );

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayDreaminaVideoMedia(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for media display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required)</small></span>
        <input id="input-jobid" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaVideosJobId()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1 ===
Document URL: https://useapi.net/docs/api-dreamina-v1

# <img style="height:1em;vertical-align: middle;" src="/assets/images/dreamina-logo.png"> Dreamina API v1
<small>February 23, 2026 (April 17, 2026)</small>

This is the [experimental](/docs/legal) API for [Dreamina](https://dreamina.capcut.com/) by [ByteDance](https://www.bytedance.com/).

[Dreamina](https://dreamina.capcut.com/) creates AI-generated videos and images using models from [ByteDance's Seed](https://seed.bytedance.com/) family.

**Video generation models:**

| Model | Region | Durations | Resolution | Input Modes |
|-------|--------|-----------|------------|-------------|
| `seedance-2.0` | US, CA | 4-15s | 720p, 1080p (CA only as of April 17) | Prompt, First/Last Frame, Omni Reference |
| `seedance-2.0-fast` | US, CA | 4-15s | 720p | Prompt, First/Last Frame, Omni Reference |
| `seedance-1.5-pro` | US, CA | 5, 10, 12s | 720p, 1080p | Prompt, First/Last Frame |
| `seedance-1.0-pro` | CA | 5, 10s | 1080p | Prompt, First Frame |
| `seedance-1.0-mini` | US, CA | 5, 10s | 720p, 1080p | Prompt, First Frame, Multi-Frame |
| `seedance-1.0-fast` | CA | 5, 10s | 720p, 1080p | Prompt, First Frame, Multi-Frame |
| `sora2` | CA | 4, 8, 12s | 720p | Prompt, First Frame |

720p works on both regions; 1080p is CA-only as of April 17, 2026. See [Setup Dreamina](/docs/start-here/setup-dreamina) for per-region setup and pricing.

**Image generation models (US and CA regions):**

| Model | Resolution | Max refs | Auto ratio | Notes |
|-------|------------|----------|------------|-------|
| `seedream-5.0-lite` | 2K / 4K | 6 | ✓ | Latest Seedream model |
| `seedream-4.6` | 2K / 4K | 6 | ✓ | Latest stable |
| `seedream-4.5` | 2K / 4K | 6 | ✓ | High quality |
| `seedream-4.1` | 2K / 4K | 6 | ✓ | |
| `seedream-4.0` | 2K / 4K | 6 | ✓ | Balanced quality/speed |
| `nano-banana` | 1K | 3 | ✓ | Fast |
| `seedream-3.0` | 1K / 2K | 1 | — | |

**Video upscale** — 2x super-resolution via [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale). Doubles both width and height (e.g., 720p to 1440p, 1080p to 4K).

**Video interpolation** — smooth frame rate boost to 30 or 60 FPS via [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Works on both original and upscaled videos.

**Image upscale** to 2K/4K/8K resolution via [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale).

<details markdown="block">
<summary><b>💲 Cost calculator</b></summary>

**CA is ~3× cheaper per second** than US for the same Seedance 2.0 models.

| Model | US $/sec | CA $/sec |
|-------|---------:|---------:|
| Seedance 2.0 Fast | $0.113 | **$0.036** |
| Seedance 2.0 (720p) | $0.138 | **$0.044** |
| Seedance 2.0 (1080p) | — | **$0.108** |

Example — 10-second clip:

* Seedance 2.0 Fast: **$1.13 on US** vs **$0.36 on CA**
* Seedance 2.0 (720p): **$1.38 on US** vs **$0.43 on CA**

Plans compared — Advanced monthly (<a href="https://dreamina.capcut.com/pricing" target="_blank">see plans</a>):

* **US:** USD$70/mo, 8,645 credits
* **CA:** C$94.90/mo ≈ USD$68/mo, 37,070 credits → **~4.3× more credits per USD**

See [Setup Dreamina → Cost calculator](/docs/start-here/setup-dreamina#cost-calculator) for the math breakdown and plan screenshots.

</details>

⚙️ [Setup Dreamina](/docs/start-here/setup-dreamina)

📦 [Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(April 17, 2026)</small>

🤖 [LLM-friendly API spec](https://useapi.net/assets/aibot/api-dreamina-v1.txt) <small>Feed this to your LLM to build integrations</small>

Examples:
* [Seedance 2.0 — real-face tutorial (Runway & Dreamina)](/blog/260415)
* [Seedance 2.0, Video Upscale](/blog/260402)
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [Seedream 4.5 and Seedance 2.0](/blog/260302)
* [Seedance 2.0](/blog/260223)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts
## Configure Dreamina Account
<small>February 23, 2026 (April 2, 2026)</small>

---

Configure your Dreamina account for API access using email and password credentials. See [Setup Dreamina](/docs/start-here/setup-dreamina) for details.
> **https://api.useapi.net/v1/dreamina/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "email": "user@example.com",
  "password": "your-password",
  "region": "CA",
  "maxJobs": 10
}
```

- `email` is **required**. Dreamina account email address.
- `password` is **required**. Dreamina account password.
- `region` is **required**. Region code. Supported values: `US`, `CA`. Both regions support Seedance 2.0 at 720p; 1080p Seedance 2.0 is CA-only as of April 17, 2026. See [Setup Dreamina](/docs/start-here/setup-dreamina) for region-specific setup.
- `maxJobs` is optional. Maximum concurrent jobs for this account (1-50, default: `10`).
### Responses

**200**
**200 OK**

Account configured successfully.

```json
{
  "account": "CA:user@example.com",
  "email": "user@example.com",
  "region": "CA",
  "maxJobs": 10,
  "sessionExpires": "2026-04-24T12:00:00.000Z",
  "session": {
    "expires": "2026-04-24T12:00:00.000Z",
    "lastRefreshed": "2026-02-23T12:00:00.000Z",
    "daysUntilExpiry": 60
  },
  "models": {
    "video": ["seedance-2.0-fast", "seedance-2.0", "seedance-1.5-pro", "seedance-1.0-pro", "seedance-1.0-fast", "sora2", "seedance-1.0-mini"],
    "image": ["seedream-5.0-lite", "seedream-4.6", "seedream-4.5", "seedream-4.1", "seedream-4.0", "nano-banana", "seedream-3.0"]
  },
  "credits": {
    "total": 500,
    "vip": 200,
    "gift": 200,
    "purchase": 100,
    "dailyClaimed": false
  }
}
```

**400**
**400 Bad Request**

Validation error (missing/invalid parameters).

```json
{
  "error": "Parameter email is required"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**500**
**500 Internal Server Error**

Login failed (bad credentials, upstream error).

```json
{
  "error": "Login failed: invalid credentials"
}
```

### Model

- `account` - Account identifier
- `email` - Dreamina account email
- `region` - Region code
- `maxJobs` - Maximum concurrent jobs
- `sessionExpires` - ISO 8601 timestamp when session expires
- `session` - Session details including refresh timing
- `models` - Available video and image generation models
- `credits` - Credit balance breakdown

```typescript
{ // TypeScript, all fields are optional
  account: string                // "CA:user@example.com"
  email: string
  region: string                 // "US" or "CA"
  maxJobs: number                // 1-50
  sessionExpires: string         // ISO 8601 timestamp
  session: {
    expires: string              // ISO 8601 timestamp
    lastRefreshed: string        // ISO 8601 timestamp
    daysUntilExpiry: number
  }
  models: {
    video: string[]              // Available video model names
    image: string[]              // Available image model names
  }
  credits: {
    total: number
    vip: number
    gift: number
    purchase: number
    dailyClaimed: boolean
  }
  error?: string                 // Error message
}
```

### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -X POST "https://api.useapi.net/v1/dreamina/accounts" \
     -d '{
       "email": "user@example.com",
       "password": "your-password",
       "region": "CA"
     }'
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/dreamina/accounts';
const token = 'YOUR_API_TOKEN';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password',
    region: 'CA'
  })
});

const result = await response.json();
console.log('Account configured:', result);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v1/dreamina/accounts'
token = 'YOUR_API_TOKEN'

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

body = {
    'email': 'user@example.com',
    'password': 'your-password',
    'region': 'CA'
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response.status_code, response.json())
```

### Try It

<script>
  async function apiTestAccountDreamina() {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-Dreamina-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let email = document.getElementById('post-accounts-Dreamina-email')?.value;
      let password = document.getElementById('post-accounts-Dreamina-password')?.value;
      let region = document.getElementById('post-accounts-Dreamina-region')?.value;

      data.body = JSON.stringify({
          email,
          password,
          region
      });

      await apiExecute(`https://api.useapi.net/v1/dreamina/accounts`, 'post-accounts-Dreamina', data);
  }
</script>

<form id="post-accounts-Dreamina" onsubmit="return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Dreamina-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Dreamina-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Dreamina-email"><span>email<small> (required)</small></span>
        <input id="post-accounts-Dreamina-email" type="text" class="input-element" required aria-required="true" placeholder="user@example.com">
      </label>
      <label for="post-accounts-Dreamina-password"><span>password<small> (required)</small></span>
        <input id="post-accounts-Dreamina-password" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="post-accounts-Dreamina-region"><span>region<small> (required)</small></span>
        <select id="post-accounts-Dreamina-region" class="input-element">
          <option value="CA">CA (Canada)</option>
          <option value="US">US</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Dreamina-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestAccountDreamina()">Go</button>
  </div>
</form>

<div id="post-accounts-Dreamina-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-assets-account ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-assets-account
## Upload Assets
<small>February 23, 2026 (April 3, 2026)</small>

---

Upload images, videos, and audio files to Dreamina for use in video and image generation.

**Images** (max 10 MB):

| Content-Type | File Extension |
| ------------ | -------------- |
| image/jpeg   | jpeg, jpg      |
| image/png    | png            |
| image/webp   | webp           |

**Videos** (max 50 MB, 2-15.4 seconds, 200-2160px):

| Content-Type | File Extension |
| ------------ | -------------- |
| video/mp4    | mp4            |
| video/quicktime | mov         |
| video/webm   | webm           |

**Audio** (max 15 MB, 2-15 seconds):

| Content-Type | File Extension |
| ------------ | -------------- |
| audio/mpeg   | mp3            |
| audio/mp3    | mp3            |
| audio/wav    | wav            |
| audio/mp4    | m4a            |
| audio/aac    | aac            |

The returned `assetRef` is used as:
- **Images:** `firstFrameRef`, `endFrameRef`, `frame_N_imageRef`, or `omni_N_imageRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), and `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images).
- **Videos:** `omni_N_videoRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) Omni Reference mode (max 3 per request, total duration max 15.4s).
- **Audio:** `omni_N_audioRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) Omni Reference mode (max 3 per request, total duration max 15s).
> **https://api.useapi.net/v1/dreamina/assets/`account`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table above
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.
- `Content-Type` is **required**, see table above.

### Path Parameters

- `account` is **required**.

### Request Body

Binary image content (raw bytes).

### Responses

**200**
**200 OK**

Asset uploaded successfully. Returns the `assetRef` for use in video and image generation.

**Image response:**
```json
{
  "assetRef": "CA:user@example.com-image:w2560:h1440:s580914-uri:tos-alisg-i-wopfjsm1ax-sg/abc123",
  "account": "CA:user@example.com",
  "width": 2560,
  "height": 1440,
  "size": 580914
}
```

**Video response:**
```json
{
  "assetRef": "CA:user@example.com-video:w1070:h1904:s1656759:d5880-vid:v10762g50003d77lv1nog65ie0vi8oh0",
  "account": "CA:user@example.com",
  "type": "video",
  "width": 1070,
  "height": 1904,
  "duration": 5880,
  "size": 1656759
}
```

**Audio response:**
```json
{
  "assetRef": "CA:user@example.com-audio:w480:h360:s562605:d14040-vid:v10762g50003d77l5uvog65nl4esjs2g",
  "account": "CA:user@example.com",
  "type": "audio",
  "duration": 14040,
  "size": 562605
}
```

- `assetRef` - Reference ID for use in generation endpoints.
- `type` - Asset type: `image`, `video`, or `audio` (omitted for images for backward compatibility).
- `width` - Width in pixels (images and videos).
- `height` - Height in pixels (images and videos).
- `duration` - Duration in milliseconds (videos and audio).
- `size` - File size in bytes.
- `account` - Account used for the upload.

**assetRef formats:**
- Image: `<account>-image:w<width>:h<height>:s<size>-uri:<nativeUri>`
- Video: `<account>-video:w<width>:h<height>:s<size>:d<durationMs>-vid:<videoId>`
- Audio: `<account>-audio:w<width>:h<height>:s<size>:d<durationMs>-vid:<videoId>`

**400**
**400 Bad Request**

Invalid request (empty content, unsupported content type, file too large, or duration out of range).

```json
{
  "error": "Content-Type (image/bmp) not supported. Valid values: image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/mp4, audio/aac"
}
```

```json
{
  "error": "video exceeds 50MB limit (52.1MB)"
}
```

```json
{
  "error": "Audio duration 16.5s exceeds 15s limit"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for account US:user@example.com"
}
```

**596**
**596 Session Error**

Account session expired. Re-add the account using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) with correct credentials.

```json
{
  "error": "Session expired"
}
```

### Model
```typescript
{
  assetRef: string                // Reference ID for POST /videos and POST /images
  account: string                 // "CA:user@example.com"
  type?: string                   // "image", "video", or "audio" (omitted for images)
  width?: number                  // Width in pixels (images and videos)
  height?: number                 // Height in pixels (images and videos)
  duration?: number               // Duration in milliseconds (videos and audio)
  size?: number                   // File size in bytes
  imageRef?: string               // Legacy alias for assetRef (backward compatibility, images only)
  error?: string                  // Error message
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: image/jpeg" \
     --data-binary @/path/to/your/image.jpeg \
     "https://api.useapi.net/v1/dreamina/assets/US:user@example.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const account = 'US:user@example.com';

const apiUrl = `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(account)}`;

// Load image - Example 1: From local file (Node.js)
const fsp = require('fs').promises;
const blob = new Blob([await fsp.readFile('./image.jpeg')]);

// Load image - Example 2: From file input element
// const imageFile = document.getElementById('image-file');
// const blob = imageFile.files[0];

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': blob.type || 'image/jpeg'
  },
  body: blob
});

const result = await response.json();
console.log('Upload result:', result);
console.log('assetRef:', result.assetRef);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
account = 'US:user@example.com'

api_url = f'https://api.useapi.net/v1/dreamina/assets/{quote(account, safe="")}'

with open('./image.jpeg', 'rb') as image_file:
    file_content = image_file.read()

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

response = requests.post(api_url, headers=headers, data=file_content)

result = response.json()
print('Upload result:', result)
print('assetRef:', result.get('assetRef'))
```

### Try It

<script>
  async function apiExecutePostDreaminaAssetAccount() {
    const tokenElement = document.getElementById('input-token');
    const accountElement = document.getElementById('input-account');
    const inputFile = document.getElementById('input-file');

    if (!inputFile.files[0]) {
      alert('Please select a file.');
      return false;
    }

    const blob = inputFile.files[0];

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': blob.type || 'image/jpeg'
      },
      body: blob
    };

    await apiExecute(
      `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(accountElement.value)}`,
      'input',
      data
    );
  }

  function clearInputFile() {
    document.getElementById('input-file').value = '';
    return false;
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (required)</small></span>
        <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com">
      </label>
      <label for="input-file"><span>Upload file</span>
        <div style="display:flex">
          <button id="input-file-clear" onclick="clearInputFile()">✖️</button>
          <input id="input-file" type="file" class="input-element" accept="image/png,image/jpeg,image/webp,video/mp4,video/quicktime,video/webm,audio/mpeg,audio/mp3,audio/wav,audio/mp4,audio/aac">
        </div>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaAssetAccount()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale
## Upscale Image
<small>March 2, 2026</small>

---

Upscale a generated image to higher resolution (2K, 4K, or 8K). Requires a completed image generation job from [POST /images](/docs/api-dreamina-v1/post-dreamina-images).

Upscale is asynchronous — poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for the result.
> **https://api.useapi.net/v1/dreamina/images/upscale**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
  "imageIndex": 0,
  "upscaleResolution": "4k"
}
```

- `jobid` is **required**. The job ID of a completed image generation job from [POST /images](/docs/api-dreamina-v1/post-dreamina-images).
- `imageIndex` is optional. Index of the image to upscale from the source job (0-3, default: `0`). Each generation produces up to 4 images.
- `upscaleResolution` is optional. Target resolution (default: `4k`). Supported values: `2k`, `4k`, `8k`.
- `originalImageStrength` is optional. How much of the original image to preserve (0-1, default: `0.65`).
- `detailStrength` is optional. Detail enhancement level (0-1, default: `0.5`).
- `replyUrl` is optional, webhook URL for job status callbacks.
  Callback body has the same JSON shape as [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

**200**
**200 OK**

Upscale job created. Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for the result.

```json
{
  "jobid": "j0302140630123456789I-u12345-US:user@example.com-bot:dreamina",
  "type": "upscale",
  "status": "created",
  "model": "seedream-4.0",
  "created": "2026-03-02T14:06:30.123Z",
  "request": {
    "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
    "imageIndex": 0,
    "resolution": "4k"
  },
  "response": {
    "forecastCost": 0
  },
  "code": 200
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter jobid is required"
}
```

```json
{
  "error": "Source image job is created, must be completed"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Source image job not found.

```json
{
  "error": "Source image job not found"
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
       "imageIndex": 0,
       "upscaleResolution": "4k"
     }' \
     "https://api.useapi.net/v1/dreamina/images/upscale"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/dreamina/images/upscale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobid: 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina',
    imageIndex: 0,
    upscaleResolution: '4k'
  })
});

const result = await response.json();
console.log('Upscale job:', result.jobid);

// Poll for completion
const poll = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const job = await res.json();
    if (job.status === 'completed') {
      console.log('Upscaled:', job.response.images[0].width, 'x', job.response.images[0].height);
      return job;
    }
    if (job.status === 'failed') throw new Error(job.error);
    await new Promise(r => setTimeout(r, 10000));
  }
};

await poll(result.jobid);
```

**Python**
``` python
import requests
import time

token = 'YOUR_API_TOKEN'

response = requests.post(
    'https://api.useapi.net/v1/dreamina/images/upscale',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'jobid': 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina',
        'imageIndex': 0,
        'upscaleResolution': '4k'
    }
)

result = response.json()
print(f"Upscale job: {result['jobid']}")

# Poll for completion
jobid = result['jobid']
while True:
    job = requests.get(
        f'https://api.useapi.net/v1/dreamina/images/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()

    if job['status'] == 'completed':
        img = job['response']['images'][0]
        print(f"Upscaled: {img['width']}x{img['height']}")
        break
    if job['status'] == 'failed':
        raise Exception(job.get('error'))

    time.sleep(10)
```

### Try It

<script>
  async function apiExecutePostDreaminaImagesUpscale() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'imageIndex' || key === 'maxJobs') {
          payload[key] = parseInt(value);
        } else if (key === 'originalImageStrength' || key === 'detailStrength') {
          payload[key] = parseFloat(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/images/upscale', elementId, data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required, from POST /images)</small></span>
        <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-imageIndex"><span>imageIndex<small> (0-3, default: 0)</small></span>
        <input id="input-imageIndex" type="number" class="input-element input-query-param" min="0" max="3" placeholder="0">
      </label>
      <label for="input-upscaleResolution"><span>upscaleResolution</span>
        <select id="input-upscaleResolution" class="input-element input-query-param">
          <option value="">4k (default)</option>
          <option value="2k">2k</option>
          <option value="4k">4k</option>
          <option value="8k">8k</option>
        </select>
      </label>
      <label for="input-originalImageStrength"><span>originalImageStrength<small> (0-1, default: 0.65)</small></span>
        <input id="input-originalImageStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.05" placeholder="0.65">
      </label>
      <label for="input-detailStrength"><span>detailStrength<small> (0-1, default: 0.5)</small></span>
        <input id="input-detailStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.1" placeholder="0.5">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaImagesUpscale()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images
## Generate Images
<small>March 4, 2026 (April 2, 2026)</small>

---

Generate images using Dreamina AI models from text prompts with optional reference images. All image generation is asynchronous — this endpoint returns immediately with a job ID. Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for completion, or use `replyUrl` webhook for automatic callbacks.

Each generation produces up to 4 images. Generation typically completes within 15-120 seconds depending on the model and resolution.

### Models (US and CA regions)

| Model | Resolutions | Default | Max Refs | Prompt Required | Auto Ratio |
|-------|-------------|---------|----------|-----------------|------------|
| `seedream-5.0-lite` <br><small>(**free**)</small> | 2k, 4k | 2k | 6 | No <br><small>(imageRef_x only)</small> | Yes |
| `seedream-4.6` <br><small>(default, **free**)</small> | 2k, 4k | 2k | 6 | No <br><small>(imageRef_x only)</small> | Yes |
| `seedream-4.5` | 2k, 4k | 2k | 6 | No <br><small>(imageRef_x only)</small> | Yes |
| `seedream-4.1` | 2k, 4k | 2k | 6 | No <br><small>(imageRef_x only)</small> | Yes |
| `seedream-4.0` <br><small>(**free**)</small> | 2k, 4k | 2k | 6 | No <br><small>(imageRef_x only)</small> | Yes |
| `nano-banana` | 1k | 1k | 3 | Yes | Yes |
| `seedream-3.0` | 1k, 2k | 1k | 1 | Yes | No |
> **https://api.useapi.net/v1/dreamina/images**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A stunning aurora borealis over a frozen lake at midnight",
  "model": "seedream-4.6",
  "ratio": "16:9",
  "resolution": "2k"
}
```

- `account` is optional. Specific account to use. Auto-selected (random with available capacity) if omitted. Not needed when `imageRef_N` provided — account is derived from the reference.
- `prompt` is **required**, optional when model supports `imageRef_N`. Maximum 1600 characters.
- `model` is optional, see [Models](#models-us-and-ca-regions) above.
- `ratio` is optional, image aspect ratio (default: `auto` for models that support it, `1:1` otherwise). Supported values: `auto`, `1:1`, `3:4`, `16:9`, `4:3`, `9:16`, `2:3`, `3:2`, `21:9`.
- `resolution` is optional, output resolution tier (default depends on model — see Model Capabilities). Supported values: `1k`, `2k`, `4k`.
- `imageRef_1`…`imageRef_6` are optional. Reference images from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) or completed image job `assetRef`. Must be contiguous, max per model see [Models](#models-us-and-ca-regions).
- `imageStrength` is optional, reference image influence strength (0-1, default: `0.5`).
- `replyUrl` is optional, webhook URL for job status callbacks.
  Callback body has the same JSON shape as [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

**200**
**200 OK**

Job created successfully. Images are generating in the background.

```json
{
  "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina",
  "type": "image",
  "status": "created",
  "model": "seedream-4.6",
  "created": "2026-03-02T14:05:30.123Z",
  "request": {
    "prompt": "A stunning aurora borealis over a frozen lake at midnight",
    "model": "seedream-4.6",
    "ratio": "16:9",
    "resolution": "2k",
    "inputMode": "generate",
    "replyUrl": "https://your-domain.com/webhook",
    "replyRef": "my-ref-123"
  },
  "response": {
    "forecastCost": 0
  },
  "code": 200
}
```

Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for completion status, or use `replyUrl` for webhook callbacks.

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter model (invalid-model) valid values: seedream-5.0-lite, seedream-4.6, seedream-4.5, seedream-4.1, seedream-4.0, nano-banana, seedream-3.0"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**429**
**429 Too Many Requests**

All accounts at maximum capacity.

```json
{
  "error": "All accounts at capacity"
}
```

### Model

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'image'                    // Job type
  status: 'created'                // Initial status
  model: string                    // Model used
  created: string                  // ISO 8601 timestamp
  request: {
    prompt?: string
    model: string
    ratio?: string
    resolution?: string
    inputMode: string              // Auto-detected from params
    imageRef_1?: string            // Reference image assetRef (when provided)
    imageRef_2?: string
    imageRef_3?: string
    replyUrl?: string
    replyRef?: string
  }
  response: {
    forecastCost: number           // Estimated credit cost
  }
  code: number                     // HTTP status code
  error?: string
}
```

### Examples

**Curl**
``` bash
# Text-to-image
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A stunning aurora borealis over a frozen lake",
       "model": "seedream-4.6",
       "ratio": "16:9",
       "resolution": "2k"
     }' \
     "https://api.useapi.net/v1/dreamina/images"

# With reference image
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A dreamy reinterpretation with soft pastel colors",
       "model": "seedream-4.1",
       "imageRef_1": "US:user@example.com-image:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
       "imageStrength": 0.5
     }' \
     "https://api.useapi.net/v1/dreamina/images"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const apiUrl = 'https://api.useapi.net/v1/dreamina/images';

// Text-to-image
const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A stunning aurora borealis over a frozen lake',
    model: 'seedream-4.6',
    ratio: '16:9',
    resolution: '2k'
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion
const poll = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const job = await res.json();
    console.log('Status:', job.status);

    if (job.status === 'completed') {
      console.log('Images:', job.response.images.length);
      job.response.images.forEach((img, i) =>
        console.log(`  [${i}] ${img.width}x${img.height} ${img.imageUrl}`)
      );
      return job;
    }
    if (job.status === 'failed') throw new Error(job.error);

    await new Promise(r => setTimeout(r, 10000));
  }
};

const completed = await poll(result.jobid);
```

**Python**
``` python
import requests
import time

token = 'YOUR_API_TOKEN'
api_url = 'https://api.useapi.net/v1/dreamina/images'

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

# Text-to-image
data = {
    'prompt': 'A stunning aurora borealis over a frozen lake',
    'model': 'seedream-4.6',
    'ratio': '16:9',
    'resolution': '2k'
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()
print(f"Job created: {result['jobid']}")

# Poll for completion
jobid = result['jobid']
while True:
    job = requests.get(
        f'https://api.useapi.net/v1/dreamina/images/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()
    print(f"Status: {job['status']}")

    if job['status'] == 'completed':
        for i, img in enumerate(job['response']['images']):
            print(f"  [{i}] {img['width']}x{img['height']} {img['imageUrl']}")
        break
    if job['status'] == 'failed':
        raise Exception(job.get('error'))

    time.sleep(10)
```

### Try It

<script>
  async function apiExecutePostDreaminaImages() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'maxJobs' || key === 'imageStrength') {
          payload[key] = parseFloat(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/images', elementId, data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (optional)</small></span>
        <input id="input-account" type="text" class="input-element input-query-param" placeholder="US:user@example.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required for T2I)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A stunning aurora borealis over a frozen lake">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="seedream-4.6">seedream-4.6 (default)</option>
          <option value="seedream-5.0-lite">seedream-5.0-lite (free)</option>
          <option value="seedream-4.5">seedream-4.5</option>
          <option value="seedream-4.1">seedream-4.1</option>
          <option value="seedream-4.0">seedream-4.0 (free)</option>
          <option value="nano-banana">nano-banana</option>
          <option value="seedream-3.0">seedream-3.0</option>
        </select>
      </label>
      <label for="input-ratio"><span>ratio</span>
        <select id="input-ratio" class="input-element input-query-param">
          <option value="">auto</option>
          <option value="1:1">1:1</option>
          <option value="3:4">3:4</option>
          <option value="16:9">16:9</option>
          <option value="4:3">4:3</option>
          <option value="9:16">9:16</option>
          <option value="2:3">2:3</option>
          <option value="3:2">3:2</option>
          <option value="21:9">21:9</option>
        </select>
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="">default</option>
          <option value="1k">1k</option>
          <option value="2k">2k</option>
          <option value="4k">4k</option>
        </select>
      </label>
      <label for="input-imageRef_1"><span>imageRef_1<small> (optional, from <a href="/docs/api-dreamina-v1/post-dreamina-assets-account">POST /assets/account</a>)</small></span>
        <input id="input-imageRef_1" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-imageRef_2"><span>imageRef_2<small> (optional)</small></span>
        <input id="input-imageRef_2" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-imageRef_3"><span>imageRef_3<small> (optional)</small></span>
        <input id="input-imageRef_3" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-imageStrength"><span>imageStrength<small> (0-1, default: 0.5)</small></span>
        <input id="input-imageStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.1" placeholder="0.5">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaImages()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-interpolate ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-interpolate
## Interpolate Video
<small>April 2, 2026</small>

---

Interpolate a generated video to higher frame rate (30 or 60 FPS from the original 24 FPS). Creates smoother motion by generating intermediate frames.

Requires a completed video generation or video upscale job. Each video can only be interpolated once. You can interpolate both original and upscaled videos.

Interpolation is asynchronous — poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result.
> **https://api.useapi.net/v1/dreamina/videos/interpolate**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina",
  "fps": 60
}
```

- `jobid` is **required**. The job ID of a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) or a completed video upscale job from [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale).
- `fps` is **required**. Target frame rate. Supported values: `30`, `60`.
- `replyUrl` is optional, webhook URL for job status callbacks.
  Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

**200**
**200 OK**

Interpolation job created. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result.

```json
{
  "jobid": "j0302140630123456789F-u12345-CA:user@example.com-bot:dreamina",
  "type": "video-interpolate",
  "status": "created",
  "model": "seedance-2.0-fast",
  "created": "2026-04-02T10:06:30.123Z",
  "request": {
    "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina",
    "fps": 60
  },
  "response": {
    "forecastCost": 66
  },
  "code": 200
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Source video job is created, must be completed"
}
```

```json
{
  "error": "Source video already interpolated: j0302140630123456789F-u12345-CA:user@example.com-bot:dreamina"
}
```

```json
{
  "error": "Parameter fps (24) valid values: 30, 60"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Source video job not found.

```json
{
  "error": "Source video job not found"
}
```

### Examples

**Curl**
``` bash
# Interpolate a generated video to 60 FPS
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jobid": "YOUR_COMPLETED_VIDEO_JOBID",
       "fps": 60
     }' \
     "https://api.useapi.net/v1/dreamina/videos/interpolate"

# Interpolate an upscaled video to 30 FPS
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jobid": "YOUR_COMPLETED_UPSCALE_JOBID",
       "fps": 30
     }' \
     "https://api.useapi.net/v1/dreamina/videos/interpolate"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/dreamina/videos/interpolate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobid: 'YOUR_COMPLETED_VIDEO_JOBID',
    fps: 60
  })
});

const result = await response.json();
console.log('Interpolate job:', result.jobid);

// Poll for completion
const poll = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const job = await res.json();
    if (job.status === 'completed') {
      console.log('Video URL:', job.response.videoUrl);
      return job;
    }
    if (job.status === 'failed') throw new Error(job.error);
    await new Promise(r => setTimeout(r, 10000));
  }
};

await poll(result.jobid);
```

**Python**
``` python
import requests
import time

token = 'YOUR_API_TOKEN'

response = requests.post(
    'https://api.useapi.net/v1/dreamina/videos/interpolate',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'jobid': 'YOUR_COMPLETED_VIDEO_JOBID',
        'fps': 60
    }
)

result = response.json()
print(f"Interpolate job: {result['jobid']}")

# Poll for completion
jobid = result['jobid']
while True:
    job = requests.get(
        f'https://api.useapi.net/v1/dreamina/videos/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()

    if job['status'] == 'completed':
        print(f"Video URL: {job['response']['videoUrl']}")
        break
    if job['status'] == 'failed':
        raise Exception(job.get('error'))

    time.sleep(10)
```

### Try It

<script>
  async function apiExecutePostDreaminaVideosInterpolate() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'fps' || key === 'maxJobs') {
          payload[key] = parseInt(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/videos/interpolate', elementId, data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required, from POST /videos or /videos/upscale)</small></span>
        <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-fps"><span>fps<small> (required)</small></span>
        <select id="input-fps" class="input-element input-query-param">
          <option value="30">30</option>
          <option value="60" selected>60</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideosInterpolate()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-upscale ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-upscale
## Upscale Video
<small>April 2, 2026</small>

---

Upscale a generated video to 2x resolution (super resolution). Doubles both width and height — for example, 720p (1280x720) becomes 1440p (2560x1440), and 1080p (1920x1080) becomes 4K (3840x2160).

Requires a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). Each video can only be upscaled once.

Upscale is asynchronous — poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result.
> **https://api.useapi.net/v1/dreamina/videos/upscale**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina"
}
```

- `jobid` is **required**. The job ID of a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). Must be a video generation job (not an upscale job).
- `replyUrl` is optional, webhook URL for job status callbacks.
  Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

**200**
**200 OK**

Upscale job created. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result.

```json
{
  "jobid": "j0302140630123456789V-u12345-CA:user@example.com-bot:dreamina",
  "type": "video-upscale",
  "status": "created",
  "model": "seedance-2.0-fast",
  "created": "2026-04-02T00:24:24.535Z",
  "request": {
    "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina"
  },
  "response": {
    "forecastCost": 30
  },
  "code": 200
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Source video job is created, must be completed"
}
```

```json
{
  "error": "Source video already upscaled: j0302140630123456789V-u12345-CA:user@example.com-bot:dreamina"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Source video job not found.

```json
{
  "error": "Source video job not found"
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jobid": "YOUR_COMPLETED_VIDEO_JOBID"
     }' \
     "https://api.useapi.net/v1/dreamina/videos/upscale"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/dreamina/videos/upscale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobid: 'YOUR_COMPLETED_VIDEO_JOBID'
  })
});

const result = await response.json();
console.log('Upscale job:', result.jobid);

// Poll for completion
const poll = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const job = await res.json();
    if (job.status === 'completed') {
      console.log('Upscaled:', job.response.width, 'x', job.response.height);
      console.log('Video URL:', job.response.videoUrl);
      return job;
    }
    if (job.status === 'failed') throw new Error(job.error);
    await new Promise(r => setTimeout(r, 10000));
  }
};

await poll(result.jobid);
```

**Python**
``` python
import requests
import time

token = 'YOUR_API_TOKEN'

response = requests.post(
    'https://api.useapi.net/v1/dreamina/videos/upscale',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'jobid': 'YOUR_COMPLETED_VIDEO_JOBID'
    }
)

result = response.json()
print(f"Upscale job: {result['jobid']}")

# Poll for completion
jobid = result['jobid']
while True:
    job = requests.get(
        f'https://api.useapi.net/v1/dreamina/videos/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()

    if job['status'] == 'completed':
        r = job['response']
        print(f"Upscaled: {r['width']}x{r['height']}")
        print(f"Video URL: {r['videoUrl']}")
        break
    if job['status'] == 'failed':
        raise Exception(job.get('error'))

    time.sleep(10)
```

### Try It

<script>
  async function apiExecutePostDreaminaVideosUpscale() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'maxJobs') {
          payload[key] = parseInt(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/videos/upscale', elementId, data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobid<small> (required, from POST /videos)</small></span>
        <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideosUpscale()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos ===
Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos
## Generate Videos
<small>February 23, 2026 (April 17, 2026)</small>

---

Generate videos using Dreamina AI models from text prompts with optional image frames. All video generation is asynchronous — this endpoint returns immediately with a job ID. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for completion, or use `replyUrl` webhook for automatic callbacks.

Video generation typically completes within 60-180 seconds depending on the model and duration.

### Input Modes

The input mode is automatically determined from the provided parameters:

| Mode | API Value | Trigger | Description |
|------|-----------|---------|-------------|
| Prompt | `prompt` | No image refs | Text-to-video generation |
| First Frame | `first_frame` | `firstFrameRef` provided | Video starts from uploaded image |
| First/Last Frame | `end_frame` | `firstFrameRef` + `endFrameRef` | Video transitions between two images |
| Multi-Frame | `multi_frame` | `frame_N_imageRef` params | 2-10 keyframe images with per-frame prompts |
| Omni Reference | `unified_edit` | `omni_N_imageRef`/`omni_N_videoRef`/`omni_N_audioRef` in prompt | Interleaved text, image, video, and audio references (Seedance 2.0 only) |
> **Aspect ratio auto-detection:** When using `first_frame` or `end_frame` modes, the video aspect ratio is automatically detected from the uploaded image dimensions. The `ratio` parameter cannot be specified with image refs — the closest standard ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16) is used. When using `firstFrameRef` + `endFrameRef`, both images must have the same aspect ratio.

### Model Capabilities

| Model | Region | Durations | Resolution | Input Modes |
|-------|--------|-----------|------------|-------------|
| `seedance-2.0` | US, CA | 4-15s | 720p, 1080p (CA only as of April 17) | Prompt, First/Last Frame, Omni Reference |
| `seedance-2.0-fast` | US, CA | 4-15s | 720p | Prompt, First/Last Frame, Omni Reference |
| `seedance-1.5-pro` | US, CA | 5, 10, 12s | 720p, 1080p | Prompt, First/Last Frame |
| `seedance-1.0-pro` | CA | 5, 10s | 1080p | Prompt, First Frame |
| `seedance-1.0-mini` | US, CA | 5, 10s | 720p, 1080p | Prompt, First Frame, Multi-Frame |
| `seedance-1.0-fast` | CA | 5, 10s | 720p, 1080p | Prompt, First Frame, Multi-Frame |
| `sora2` | CA | 4, 8, 12s | 720p | Prompt, First Frame |

720p works on both regions; 1080p is CA-only as of April 17, 2026. See [Setup Dreamina](/docs/start-here/setup-dreamina) for per-region setup and pricing.
> **Seedance 2.0 / 2.0 Fast:** Real human faces are not supported and may be rejected by content moderation. Use illustrated, anime, or stylized characters instead. For a working real-face workflow, see the [Seedance 2.0 — real-face tutorial (Runway & Dreamina)](/blog/260415) — it uses Runway to generate the real-face start frame and Dreamina Seedance 2.0 for the motion, sidestepping Dreamina's direct content moderation.
> **https://api.useapi.net/v1/dreamina/videos**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
  "model": "seedance-2.0",
  "ratio": "16:9",
  "duration": 5
}
```

- `account` is optional. Specific account to use. Auto-inferred from image refs if provided. Auto-selected (random with available capacity) if omitted.
- `prompt` is **required** for `prompt` mode. Optional for `first_frame` and `end_frame`. Cannot be used with `multi_frame` mode (use `frame_N_prompt` instead). Maximum 5000 characters.
- `model` is optional, the AI model to use (default: `seedance-2.0`). Available models depend on account region — see Model Capabilities table.
- `ratio` is optional, video aspect ratio (default: `16:9`). Cannot be specified when image refs are provided (image aspect ratio is used).
- `duration` is optional, video duration in seconds (default: `5`). Valid values depend on model — see Model Capabilities table.
- `resolution` is optional, output resolution: `720p` or `1080p` (default: `720p`). Supported by `seedance-2.0` (CA accounts only at 1080p), `seedance-1.5-pro`, `seedance-1.0-mini`, and `seedance-1.0-fast`. Model `seedance-1.0-pro` is always `1080p`. `seedance-2.0-fast` and `sora2` are 720p only.
- `firstFrameRef` is optional, `imageRef` from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) for the starting frame. Triggers `first_frame` mode.
- `endFrameRef` is optional, `imageRef` for the ending frame. Triggers `end_frame` mode. Requires `firstFrameRef`.
- `frame_N_imageRef` is optional (N=1-10), `imageRef` for keyframe N. Triggers `multi_frame` mode when at least 2 frames are provided.
- `frame_N_prompt` is optional, per-frame prompt for multi_frame mode. Maximum 5000 characters.
- `frame_N_duration` is optional, per-frame duration in seconds for multi_frame mode (1-6, default: `5`).
- `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with the job record on submission and on completion/failure.
  Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `omni_N_imageRef` is optional (N=1-9), `assetRef` (image type) for inline image in Omni Reference mode. Reference in the prompt using `@imageN` (e.g., `"Make @image1 dance with @image2"`). Requires Seedance 2.0 or 2.0 Fast.
- `omni_N_videoRef` is optional (N=1-3), `assetRef` (video type) for inline video in Omni Reference mode. Upload video via [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) with `Content-Type: video/mp4`. Reference in the prompt using `@videoN` (e.g., `"@image1 moving like @video1"`).
- `omni_N_audioRef` is optional (N=1-3), `assetRef` (audio type) for inline audio in Omni Reference mode. Upload audio via [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) with `Content-Type: audio/mpeg`. Reference in the prompt using `@audioN` (e.g., `"@image1 dancing while @audio1 plays"`).
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

**Omni Reference constraints:**
- Only supported by `seedance-2.0` and `seedance-2.0-fast` models
- Prompt must contain `@imageN`, `@videoN`, and/or `@audioN` placeholders matching the provided `omni_N_*Ref` params
- Maximum 9 image references, 3 video references, and 3 audio references per request
- Maximum 12 total materials combined
- Total video duration across all `omni_N_videoRef` cannot exceed 15.4 seconds
- Total audio duration across all `omni_N_audioRef` cannot exceed 15 seconds
- Individual video: 2-15.4 seconds, 200-2160px, max 50 MB
- Individual audio: 2-15 seconds, max 15 MB
- Cannot be combined with `firstFrameRef`, `endFrameRef`, or `frame_N_imageRef`

**Multi-frame constraints:**
- Minimum 2 frames, maximum 10 frames
- No gaps allowed (frame_1 through frame_N must be contiguous)
- All frame images must have the same aspect ratio
- Top-level `prompt` cannot be used (use `frame_N_prompt` instead)
- `firstFrameRef`/`endFrameRef` cannot be combined with multi_frame
- Total duration of non-last frames must equal a valid model duration

### Responses

**200**
**200 OK**

Job created successfully. Video is generating in the background.

```json
{
  "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina",
  "type": "video",
  "status": "created",
  "model": "seedance-2.0",
  "created": "2026-02-23T14:05:30.123Z",
  "request": {
    "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
    "model": "seedance-2.0",
    "ratio": "16:9",
    "duration": 5,
    "inputMode": "prompt"
  },
  "response": {
    "forecastCost": 125
  },
  "code": 200
}
```

Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for completion status, or use `replyUrl` for webhook callbacks.

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter model (invalid-model) valid values: seedance-2.0, seedance-1.5-pro, seedance-1.0-mini"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**429**
**429 Too Many Requests**

All accounts at maximum capacity. Wait for current jobs to complete or increase `maxJobs`.

```json
{
  "error": "All accounts at capacity"
}
```

**596**
**596 Session Error**

Account session expired. Re-add the account using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) with correct credentials.

```json
{
  "error": "Session expired"
}
```

### Model

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'video'                    // Job type
  status: 'created'                // Initial status
  model: string                    // Model used
  created: string                  // ISO 8601 timestamp
  request: {
    prompt?: string
    model: string
    ratio?: string                 // "16:9", "9:16", etc.
    duration?: number              // Seconds
    inputMode: string              // "prompt" | "first_frame" | "end_frame" | "multi_frame" | "unified_edit"
    resolution?: string            // "720p" or "1080p"
    firstFrameRef?: string         // assetRef (image) for first frame
    endFrameRef?: string           // assetRef (image) for end frame
    frame_1_imageRef?: string      // Keyframe refs (multi_frame mode)
    frame_1_prompt?: string
    frame_1_duration?: number
    frame_2_imageRef?: string
    frame_2_prompt?: string
    frame_2_duration?: number
    omni_1_imageRef?: string       // Omni image refs (use @image1 in prompt)
    omni_2_imageRef?: string
    omni_1_videoRef?: string       // Omni video refs (use @video1 in prompt)
    omni_1_audioRef?: string       // Omni audio refs (use @audio1 in prompt)
    replyUrl?: string              // Webhook URL
    replyRef?: string              // Custom reference
  }
  response: {
    forecastCost: number           // Estimated credit cost
  }
  code: number                     // HTTP status code
  error?: string                   // Error message
}
```

### Examples

**Curl**
``` bash
# Text-to-video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A serene mountain landscape at sunset",
       "model": "seedance-2.0",
       "ratio": "16:9",
       "duration": 5
     }' \
     "https://api.useapi.net/v1/dreamina/videos"

# Image-to-video (first frame — ratio auto-detected from image)
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "Camera slowly pans across the scene",
       "model": "seedance-2.0",
       "firstFrameRef": "CA:user@example.com-image:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
       "duration": 5
     }' \
     "https://api.useapi.net/v1/dreamina/videos"

# Omni Reference (image + audio)
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "@image1 slowly moving forward while @audio1 plays in background",
       "model": "seedance-2.0",
       "ratio": "16:9",
       "duration": 4,
       "omni_1_imageRef": "CA:user@example.com-image:w2560:h1440:s580914-uri:tos-alisg-i-wopfjsm1ax-sg/abc123",
       "omni_1_audioRef": "CA:user@example.com-audio:d14040-vid:v10762g50003d77l5uvog65nl4esjs2g"
     }' \
     "https://api.useapi.net/v1/dreamina/videos"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const apiUrl = 'https://api.useapi.net/v1/dreamina/videos';

// Text-to-video
const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset',
    model: 'seedance-2.0',
    ratio: '16:9',
    duration: 5
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion
const poll = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const job = await res.json();
    console.log('Status:', job.status);

    if (job.status === 'completed') {
      console.log('Video URL:', job.response.videoUrl);
      return job;
    }
    if (job.status === 'failed') throw new Error(job.error);

    await new Promise(r => setTimeout(r, 10000));
  }
};

const completed = await poll(result.jobid);
```

**Python**
``` python
import requests
import time

token = 'YOUR_API_TOKEN'
api_url = 'https://api.useapi.net/v1/dreamina/videos'

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

# Text-to-video
data = {
    'prompt': 'A serene mountain landscape at sunset',
    'model': 'seedance-2.0',
    'ratio': '16:9',
    'duration': 5
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()
print(f"Job created: {result['jobid']}")

# Poll for completion
jobid = result['jobid']
while True:
    job = requests.get(
        f'https://api.useapi.net/v1/dreamina/videos/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()
    print(f"Status: {job['status']}")

    if job['status'] == 'completed':
        print(f"Video URL: {job['response']['videoUrl']}")
        break
    if job['status'] == 'failed':
        raise Exception(job.get('error'))

    time.sleep(10)
```

### Try It

<script>
  async function apiExecutePostDreaminaVideos() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'duration' || key === 'maxJobs') {
          payload[key] = parseInt(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    await apiExecute('https://api.useapi.net/v1/dreamina/videos', elementId, data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-account"><span>account<small> (optional)</small></span>
        <input id="input-account" type="text" class="input-element input-query-param" placeholder="CA:user@example.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required for T2V)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A serene mountain landscape">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="">default</option>
          <option value="seedance-2.0">seedance-2.0</option>
          <option value="seedance-2.0-fast">seedance-2.0-fast</option>
          <option value="seedance-1.5-pro">seedance-1.5-pro</option>
          <option value="seedance-1.0-pro">seedance-1.0-pro (CA only)</option>
          <option value="seedance-1.0-mini">seedance-1.0-mini</option>
          <option value="seedance-1.0-fast">seedance-1.0-fast (CA only)</option>
          <option value="sora2">sora2 (CA only)</option>
        </select>
      </label>
      <label for="input-ratio"><span>ratio</span>
        <select id="input-ratio" class="input-element input-query-param">
          <option value="">auto (from image or 16:9)</option>
          <option value="21:9">21:9</option>
          <option value="16:9">16:9</option>
          <option value="4:3">4:3</option>
          <option value="1:1">1:1</option>
          <option value="3:4">3:4</option>
          <option value="9:16">9:16</option>
        </select>
      </label>
      <label for="input-duration"><span>duration<small> (seconds)</small></span>
        <input id="input-duration" type="number" class="input-element input-query-param" min="4" max="15" placeholder="5">
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="">720p (default)</option>
          <option value="720p">720p</option>
          <option value="1080p">1080p</option>
        </select>
      </label>
      <label for="input-firstFrameRef"><span>firstFrameRef<small> (optional, from <a href="/docs/api-dreamina-v1/post-dreamina-assets-account">POST /assets/account</a>)</small></span>
        <input id="input-firstFrameRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-endFrameRef"><span>endFrameRef<small> (optional, requires firstFrameRef)</small></span>
        <input id="input-endFrameRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-frame_1_imageRef"><span>frame_1_imageRef<small> (multi-frame, seedance-1.0-mini)</small></span>
        <input id="input-frame_1_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-frame_1_prompt"><span>frame_1_prompt</span>
        <input id="input-frame_1_prompt" type="text" class="input-element input-query-param" placeholder="A person standing in a garden">
      </label>
      <label for="input-frame_1_duration"><span>frame_1_duration<small> (1-6, default: 5)</small></span>
        <input id="input-frame_1_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5">
      </label>
      <label for="input-frame_2_imageRef"><span>frame_2_imageRef</span>
        <input id="input-frame_2_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-frame_2_prompt"><span>frame_2_prompt</span>
        <input id="input-frame_2_prompt" type="text" class="input-element input-query-param" placeholder="The person walks away slowly">
      </label>
      <label for="input-frame_2_duration"><span>frame_2_duration<small> (1-6, default: 5)</small></span>
        <input id="input-frame_2_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5">
      </label>
      <label for="input-frame_3_imageRef"><span>frame_3_imageRef</span>
        <input id="input-frame_3_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-frame_3_prompt"><span>frame_3_prompt</span>
        <input id="input-frame_3_prompt" type="text" class="input-element input-query-param" placeholder="A wide shot of the garden at sunset">
      </label>
      <label for="input-frame_3_duration"><span>frame_3_duration<small> (1-6, default: 5)</small></span>
        <input id="input-frame_3_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5">
      </label>
      <label for="input-omni_1_imageRef"><span>omni_1_imageRef<small> (Omni, use @image1 in prompt)</small></span>
        <input id="input-omni_1_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-omni_2_imageRef"><span>omni_2_imageRef<small> (use @image2 in prompt)</small></span>
        <input id="input-omni_2_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:...">
      </label>
      <label for="input-omni_1_videoRef"><span>omni_1_videoRef<small> (use @video1 in prompt)</small></span>
        <input id="input-omni_1_videoRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-video:w720:h1280:d8000-vid:...">
      </label>
      <label for="input-omni_1_audioRef"><span>omni_1_audioRef<small> (use @audio1 in prompt)</small></span>
        <input id="input-omni_1_audioRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-audio:d14040-vid:...">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideos()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/start-here/setup-faceswap ===
Document URL: https://useapi.net/docs/start-here/setup-faceswap
# <img style="height:1.8em;vertical-align: middle;" src="/assets/images/picsi.png"> Setup InsightFaceSwap 
## Table of contents
<small>Approximately 3 minutes to complete setup steps.</small>  

---
> This is the setup guide for [InsightFaceSwap API](/docs/api-faceswap-v1). A [Discord](https://discord.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

## Create Discord account

You need a [Discord](https://discord.com) account to interact with [InsightFaceSwap Discord bot](https://discord.gg/Ym3X8U59ZN). Create a [new account](https://discord.com/register) if you don't have one already.

Please note even if you have an existing Discord account we are **strongly** recommending creating a separate Discord account specifically designated to be used with useapi.net API.   

## Create Discord server 

Please log in to your Discord account and create a new Discord server following [official instructions](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server-).

## Create `#api` text channel on your Discord server 

Once you created the Discord server you need to create a designated for API-related work text channel. You can refer to [official instructions](https://support.discord.com/hc/en-us/articles/4412085582359-Text-Channels-Text-Chat-In-Voice-Channels) to learn about Discord channels and how to manage them on your server. We suggest naming the text channel `#api` for clarity and also making that channel private. Please see [Midjourney instructions](https://docs.midjourney.com/docs/invite-the-bot) to learn how you can restrict the bot to a single private channel.

## Join Picsi.Ai - Powered by InsightFace Discord Server 

Follow Picsi.Ai [instructions](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md) and join official [Picsi.Ai - Powered by InsightFace Discord Server](https://discord.gg/Ym3X8U59ZN).

## Add InsightFaceSwap bot to your Discord server 

Please follow [official instructions](https://discord.com/channels/1095014106576212101/1128550062683865178/1189604165006135379) to add InsightFaceSwap bot to your Discord server created earlier.

## Example of Discord server with private `#api` text channel and InsightFace bot 

Below you can see we created `useapi` Discord server with private `#api` text channel:

![](/assets/images/discord_faceswap_server_setup_example.png)

InsightFace bot invited to the server and has access to private `#api` text channel

![](/assets/images/discord_faceswap_channel_setup_example.png)

## Test InsightFace bot

Navigate to the created above `#api` text channel and execute few InsightFaceSwap bot command(s) to make sure it works.

## Make a note of your server id and channel id values

Your Discord URL looks like `https://discord.com/channels/<server_id>/<chanel_id>` 

In the screenshot above URL is `https://discord.com/channels/1122226477161144546/1122277481822456166` where `1122226477161144546` is your Discord <u>server id</u> and `1122277481822456166` is your private `#api` <u>channel id</u>.

Save both server id and channel id values, you will need those numbers for API.

## Obtain Discord token

There are many tutorials describing how to obtain Discord tokens. Please refer to the following links bellow for additional guidance:
- [How to Find Your Discord Token](https://discordhelp.net/discord-token)
- [How To Get Your Discord Token](https://pcstrike.com/how-to-get-discord-token/)
- [How to get Discord Token](https://linuxhint.com/get-discord-token/)

Keep in mind that anyone with a Discord token can have **full access** to your Discord account so please keep it **safe** and **secure**. To reset your Discord token simply change your Discord password.

## Verify Discord access

<script>
  async function verifyServer() {
    const discord = document.getElementById(`server-discord`)?.value;
    const server = document.getElementById(`server-server`)?.value;      

    const data = { 
        method: 'GET',
        headers: {
          'Authorization': `${discord}`,
          'Content-Type': 'application/json'
        }
      };

      const url=`https://discord.com/api/v10/guilds/${server}`;

      await apiExecute(url, 'server', data);
}  

async function verifyChannel() {
    const discord = document.getElementById(`channel-discord`)?.value;
    const channel = document.getElementById(`channel-channel`)?.value;      

    const data = { 
        method: 'GET',
        headers: {
          'Authorization': `${discord}`,
          'Content-Type': 'application/json'
        }
      };

      const url=`https://discord.com/api/v10/channels/${channel}`;

      await apiExecute(url, 'channel', data);
}
</script>

Once all the above steps are completed you should have the following:
- Discord token
- Discord server id number
- Discord private `#api` channel id number

This only verifies that the token, server id and channel id values are correct. To complete setup, you **MUST** proceed to [POST account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel) and complete the configuration.

##### Server 
<form id="server" onsubmit="verifyServer(); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="server-discord"><span>Discord token</span>
        <input id="server-discord" type="text"  class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="server-server"><span>Discord server id</span>
        <input id="server-server" type="text"  class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
    </div>
    <button id="server-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="server-response" class="response-placeholder visible-false"></div>

##### Channel
<form id="channel" onsubmit="verifyChannel(); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="channel-discord"><span>Discord token</span>
        <input id="channel-discord" type="text"  class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="channel-channel"><span>Discord channel id</span>
        <input id="channel-channel" type="text"  class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
    </div>
    <button id="channel-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="channel-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-faceswap-v1 ===
Document URL: https://useapi.net/docs/api-faceswap-v1

# <img style="height:1.8em;vertical-align: middle;" src="/assets/images/picsi.png"> InsightFaceSwap API v1 
<small>February 2024</small>

This is [experimental](/docs/legal) API for [InsightFaceSwap Discord Bot](https://discord.gg/Ym3X8U59ZN) by [Picsi.Ai](https://www.picsi.ai/). InsightFaceSwap allows users to swap faces from source image(s) onto different target images. It offers free and paid [subscription](https://www.patreon.com/picsi) models. Paid subscribers have access to a wide selection of extra features such as [HiFidelity Mode](https://www.patreon.com/posts/89036144), [ARTIFY](https://www.patreon.com/posts/picsi-ai-v2-0-97389077), oldify/youngify, morphing multiple faces in one image, and [many more](https://discord.com/channels/1095014106576212101/1128550062683865178).

[Setup InsightFaceSwap](/docs/start-here/setup-faceswap)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(January 20, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-faceswap-v1.txt) <small>Feed this to your LLM to build integrations</small>

Official documentation links:
- [Discord support channel](https://discord.com/channels/1095014106576212101/1128550062683865178) 
- [Patreon support channel](https://www.patreon.com/picsi/posts)
- [YouTube channel](https://www.youtube.com/@PicsiAi)
  
#### Example source code on GitHub 
* [Face swap and animate images generated by Midjourney using InsightFaceSwap and Pika (using webhook)](https://github.com/useapi/examples/tree/main/imagine-faceswap-animate) February 19, 2024

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/aiAPI"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> Reddit Group</a>

=== URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-account-channel ===
Document URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-account-channel
## Delete InsightFaceSwap account
---
> **https://api.useapi.net/v1/faceswap/account/`channel`**

The `channel` value should correspond to an account configured previously via a [POST](/docs/api-faceswap-v1/post-faceswap-account-channel) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/faceswap/account/<channel> 
```

**JavaScript**
``` javascript
const channel = "Previously configured channel id"; 
const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
channel = "Previously configured channel id" 
apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid
## InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) command 
---

Use this endpoint to submit the InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/delid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/delid**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `idname` is **required**, please refer to InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) for details.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.  

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-delid",
    "status": "completed",
    "idname": "me",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
     "content": "idname me deleted",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param idname is missing or empty"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/delid](#insightfaceswap-delid-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-delid',
  status: 'completed' | 'failed',
  idname: string,
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/faceswap/delid \
     -F "channel=<Discord channel id>" \
     -F "idname=<idname>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/delid";
    const token = "API token";
    const channel = "Discord channel";
    const idname = "idname";
    const data = {
        method: 'DELETE',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("channel", channel);
    formData.append("idname", idname);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/delid"
token = "API token"
channel = "Discord channel"
idname = "idname"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'channel': (None, channel),
    'idname': (None, idname)
}

response = requests.delete(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account-channel ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account-channel
## Retrieve InsightFaceSwap configuration for `channel` 
---
> **https://api.useapi.net/v1/faceswap/account/`channel`**

The `channel` value should correspond to an account configured previously via a [POST](/docs/api-faceswap-v1/post-faceswap-account-channel) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "server": "Discord server id",
  "channel": "Discord channel id",
  "discord": "Discord token",
  "credits": {
  "timestamp": "2024-02-01T02:05:24.991000+00:00",
    "total": 50,
    "used": 18
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string,
  server: string, 
  channel: string,
  credits: {
    timestamp: string,
    total:  number,
    used: number
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/faceswap/account/<channel> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const channel = "Previously configured channel id"; 
const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channel}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
channel = "Previously configured channel id"
apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account
## Retrieve InsightFaceSwap accounts information
---

Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord account. You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot.

This endpoint retrieves the complete list of configured accounts for InsightFaceSwap.
> **https://api.useapi.net/v1/faceswap/account**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "Discord channel A": {
        "server": "Discord server A",
        "channel": "Discord channel A",
        "discord": "Discord token A",
        "credits": {
            "timestamp": "2024-02-01T02:05:24.991000+00:00",
            "total": 50,
            "used": 18
        },
    },
    "Discord channel B": {
        "server": "Discord server B",
        "channel": "Discord channel B",
        "discord": "Discord token B"
    },
    "Discord channel N": {
        "server": "Discord server N",
        "channel": "Discord channel N",
        "discord": "Discord token N",
        "credits": {
            "timestamp": "2024-02-01T03:17:48.159000+00:00",
            "total": 200,
            "used": 115
        }
    }    
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [channel: string]: {
    discord: string,
    server: string, 
    channel: string,
    credits: {
      timestamp: string,
      total:  number,
      used: number
    }
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/faceswap/account \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/faceswap/account"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/faceswap/account"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid

## Retrieve InsightFaceSwap job status and results
---

Use this endpoint to retrieve status and results of 
- [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot)
- [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg)
- [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started`

If you specified optional parameter [`replyUrl`](/docs/api-faceswap-v1/post-faceswap-headshot#request-body) you technically do not need to use this endpoint to retrieve results since API will call provided `replyUrl` once job generation completed.

**Important** API periodically polls (checks) Discord every 15 to 60 seconds (depending on the load) and updates all currently executed jobs statuses and results. Polling interval is used for safety reasons, aiming to prevent any potential issues with Discord and InsightFaceSwap, such as bans or excessive requests.

Jobs lifespan guaranteed to be at least 31 days, after that they will be expired and may be recycled.
> **https://api.useapi.net/v1/faceswap/jobs/?jobid=`jobid`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameter
`jobid` is **required**, use value returned by 
- [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot)
- [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg)
- [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started`

##### Responses 
**200**

**200 OK**

If field `status` value is *created*, *started* or *progress* wait in a loop for **at least** 10..30 seconds and retry again. When completed retrieve generated images or video from `attachments` array. Field `content` contains message generated by InsightFaceSwap reflecting current generation parameters and progress. Optional array `embeds` contains additional information.  

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-headshot",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:19:20.256Z",
    "prompt": "me, a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id>  Picsi.Ai Headshot Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square'] [time: <time>] [SaveID: 'me'] (796/800 credits remaining)",
    "timestamp": "2023-09-09T02:05:24.991000+00:00",
    "attachments": [
        {
            "url": "<generated image url>",
            "proxy_url": "<generated proxy image url>",
            "width": 768,
            "height": 768,
            "content_type": "<generated image type>",
            "id": "<Discord attachment id>",
            "filename": "<generated image filename>",
            "size": 7204115
        }
    ],
    "code": 200
}
```

**400**

**400 Bad Request**

```json
{
    "error": "Query param jobid not provided",
    "code": 400
}
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**

**404 Not Found**

```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```

**410**

**410 Gone**

```json
{
    "error": "Job has expired",
    "code": 410
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  jobid: string,
  parentJobId: string,
  verb:  'faceswap-changebg' | 'faceswap-headshot' | 'faceswap-picsi' |
         'faceswap-swapid' | 'faceswap-saveid' | 'faceswap-setid' | 'faceswap-INSwapper' | 
         'faceswap-listid' | 'faceswap-delall' | 'faceswap-delid' | 'faceswap-swap',
  status: 'created' | 'started' | 'moderated' | 'progress' | 
          'completed' | 'failed' | 'cancelled',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  prompt: string,
  a_background_photo_of: string,
  options: string,
  image: { size: number, type: string  },
  source_image: { size: number, type: string  },
  target_image_gif_or_video: { size: number, type: string  },
  idname: string,
  saveid_idname: string,
  saveid_image: { size: number, type: string  },
  swapid_idname: string,
  swapid_image: { size: number, type: string  },
  targetMessageId: string,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap reflecting current generation parameters and progress
  timestamp: string,
  attachments: [
      {
          id: string,
          content_type: string,
          filename: string,
          url: string,
          proxy_url: string,
          size: number,
          width: number,
          height: number
      }
  ],
  embeds: [
      {
          type: string,
          description: string,
          image: {
              url: string,
              proxy_url: string,
              width: number,
              height: number
          }
      }
  ], 
  error: string,
  errorDetails: string,
  code: 200
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/faceswap/jobs/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi";      
const apiUrl = `https://api.useapi.net/v1/faceswap/jobs/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi"
apiUrl = f"https://api.useapi.net/v1/faceswap/jobs/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs-cancel ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs-cancel

## Cancel InsightFaceSwap job
---

Cancel execution of job created by 
- [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot)
- [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg)
- [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started`
> **https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=`jobid`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameter
`jobid` is **required**, use value returned by 
- [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot)
- [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg)
- [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started`

##### Responses 
**200**

```json
{
    "jobid": "<jobid>",
    "status": "cancelled"
}   "code": 200
```

**400**

**400 Bad Request**

```json
{
    "error": "Query param jobid not provided",
    "code": 400
}
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**

**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**

**404 Not Found**

```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  status: 'created' | 'started' | 'moderated' | 'progress' | 
          'completed' | 'failed' | 'cancelled',
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi";      
const apiUrl = `https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi"
apiUrl = f"https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs

## Get list of currently executing InsightFaceSwap jobs
---
> **https://api.useapi.net/v1/faceswap/jobs**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 
**200**

**200 OK**

```json
[ "<jobid>", "<jobid>", "<jobid>" ]
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**

**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

##### Model
```typescript
// TypeScript
string[]
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/faceswap/jobs \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/faceswap/jobs`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/faceswap/jobs"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-account-channel ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-account-channel
## Create or update InsightFaceSwap account information
---

Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord account. You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot.
> **https://api.useapi.net/v1/faceswap/account/`channel`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id"
}
```
- `discord`, `channel` and `server` are **required**. Please see [Setup InsightFaceSwap](/docs/start-here/setup-faceswap) for details. 

- `channel` value specified in the request body **must match** the channel value specified in the URL path https://api.useapi.net/v1/faceswap/account/`channel`.

##### Responses 

**204**
**204 No Content** 

**400**
**400 Bad Request**
```json
{
  "error": 
    "Required param discord is missing or empty"
    "Required param server is missing or empty"
    "Required param channel is missing or empty"
    "Required param channel (<server>) is not valid Discord channel id"
    "Required param channel (<channel>) is not valid Discord channel id"
    "Required param channel (<channel>) not matching to /faceswap/account/<channel>"
    "Channel <channel> configuration has same discord value"
    "Channel <channel> configuration has same server value"
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string, 
  server: string,
  channel: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/account/<channel> \
     -d '{"discord": "…", "server": "…", "channel": …}'
```

**JavaScript**
``` javascript
const channel = "Discord channel id";      
const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channel}`; 
const token = "API token";
const discord = "Discord token";
const server = "Discord server id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  discord, server, channel
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
channel = "Discord channel id"
apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}" 
token = "API token"
discord = "Discord token"
server = "Discord server id"
maxJobs = 10
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "discord": f"{discord}", 
    "server": f"{server}",
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg
## InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command 
---

Use this endpoint to submit the InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) endpoint.  

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/changebg` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/changebg**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "a_background_photo_of": "Background prompt",
    "image": "Image File or Blob",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional, if omitted a randomly selected [configured](/docs/api-faceswap-v1/post-faceswap-account-channel) channel with available credits will be used.

- `a_background_photo_of` is **required**, background prompt, please refer to InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) for details.

- `image` is **required**, source image. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`.

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-changebg",
    "status": "started",
    "a_background_photo_of": "sunny beach",
    "image": { "size": 1699405, "type": "image/png" },
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> Picsi.Ai ChangeBG Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'sunny beach'] [time: <time>] [SaveID: '_'] (796/800 credits remaining)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param a_background_photo_of is missing or empty"
      "Required param image is missing or empty"
      "Param image is not File or Blob"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/changebg](#insightfaceswap-changebg-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-changebg',
  status: 'started' | 'failed',
  a_background_photo_of: string,
  image: { size: number, type: string },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/changebg \
     -F "channel=<Discord channel id>" \
     -F 'image=@"<Path to the image>"' \
     -F "a_background_photo_of=<a_background_photo_of>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/changebg";
    const token = "API token";
    const a_background_photo_of = "a_background_photo_of";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("a_background_photo_of", a_background_photo_of);
    formData.append("channel", channel);
    /*
        // Example 1: Fetch image from URL
        const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
        const responseImage = await fetch(imageUrl);
        formData.append("image", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./target_photo.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("image", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="target-photo-image-file" type="file"> 
        const imageFile = document.getElementById(`target-photo-image-file`);
        if (imageFile.files[0])
            formData.append("image", imageFile.files[0]);
    */
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/changebg"
token = "API token"
a_background_photo_of = "a_background_photo_of"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'a_background_photo_of': (None, a_background_photo_of),
    'channel': (None, channel)
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# image_content = response_image.content
# files['image'] = ('image.jpg', image_content, 'image/jpeg')

# # Example 2: Load image from local file
# image_file_path = "./target_photo.png"
# with open(image_file_path, 'rb') as image_file:
#     files['image'] = ('target_photo.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall
## InsightFaceSwap [/delall](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delall) command 
---

Use this endpoint to submit the InsightFaceSwap [/delall](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delall) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/delall` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/delall**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-delall",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "All idnames deleted",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/delall](#insightfaceswap-delall-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-delall',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/faceswap/delall \
     -F "channel=<Discord channel id>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/delall";
    const token = "API token";
    const channel = "Discord channel";
    const data = {
        method: 'DELETE',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("channel", channel);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/delall"
token = "API token"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'channel': (None, channel)
}

response = requests.delete(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot
## InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command 
---

Use this endpoint to submit the InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) endpoint.  

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/headshot` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/headshot**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
# Alternatively you can use application/json
# Content-Type: application/json 
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "prompt": "Background prompt",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required**, please refer to InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) for details.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`.

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-headshot",
    "status": "started",
    "prompt": "me, a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id>  Picsi.Ai Headshot Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square'] [time: <time>] [SaveID: 'me'] (796/800 credits remaining)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param prompt is missing or empty"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/headshot](#insightfaceswap-headshot-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-headshot',
  status: 'started' | 'failed',
  prompt: string,
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/headshot \
     -F "channel=<Discord channel id>" \
     -F "prompt=<prompt>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/headshot";
    const token = "API token";
    const prompt = "prompt";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("prompt", prompt);
    formData.append("channel", channel);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/headshot"
token = "API token"
prompt = "prompt"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'prompt': (None, prompt),
    'channel': (None, channel)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper
## InsightFaceSwap [Apps/INSwapper](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#appsinswapper) command 
---

Use this endpoint to submit the InsightFaceSwap [Apps/INSwapper](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#appsinswapper) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

If you already have a message in your channel with an attached image, you can use this endpoint to perform a face swap on the image contained in that message. You need `message.id` returned by [messages](https://discord.com/developers/docs/resources/channel#get-channel-messages) GET request https://discord.com/api/v10/channels/channel_id/messages ([article](/docs/articles/discord-api-part-1#finally-retrieve-imagine-commandresults)). 

You can also use field `messageId` returned by [Midjouney API v2](https://useapi.net/docs/api-v2/get-jobs-jobid#responses).

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/inswapper` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/inswapper**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "targetMessageId": "Discord message id with attached image"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `targetMessageId` is **required**, Discord message id with an attached image. The message must be located in the channel specified by the channel param mentioned above.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated image.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-inswapper",
    "status": "completed",
    "targetMessageId": "1106423469968976446",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "Picsi.Ai ver.2.0 [SaveID: 'me'] [<@Discord user id>] (90/200 credits used)",
    "attachments": [
      {
        "url": "<generated image url>",
        "proxy_url": "<generated proxy image url>",
        "width": 2048,
        "height": 2048,
        "content_type": "<generated image type>",
        "id": "<Discord image id>",
        "filename": "<generated image name>",
        "size": 7204115
      }
    ],
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param targetMessageId is missing or empty"
      "Required param targetMessageId (<targetMessageId>) is not valid Discord message id"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**
**404 Not Found**

```json
{
    "error": 
      "Unable to locate message <targetMessageId> is channel <channel>"
      "Unable to locate attachments for message <targetMessageId>"
    "code": 404
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new faceswap/inswapper requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-inswapper',
  status: 'completed' | 'failed',
  targetMessageId: string,
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  attachments: [
      {
          id: string,
          content_type: string,
          filename: string,
          url: string,
          proxy_url: string,
          size: number,
          width: number,
          height: number
      }
  ],  
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/inswapper \
     -F "channel=<Discord channel id>" \
     -F "targetMessageId=<Discord message id>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/inswapper";
    const token = "API token";
    const targetMessageId = "Discord message id";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("targetMessageId", targetMessageId);
    formData.append("channel", channel);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/inswapper"
token = "API token"
targetMessageId = "Discord message id"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'targetMessageId': (None, targetMessageId),
    'channel': (None, channel)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid
## InsightFaceSwap [/listid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#listid) command 
---

Use this endpoint to submit the InsightFaceSwap [/listid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#listid) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/listid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/listid**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-listid",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "{'id-list': ['ttt']}\n{'current-idname': 'ttt'}\n{'subscription': 'Free'}\n{'credits': '0/50'}",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/listid](#insightfaceswap-listid-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-listid',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/listid \
     -F "channel=<Discord channel id>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/listid";
    const token = "API token";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("channel", channel);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/listid"
token = "API token"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'channel': (None, channel)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi
## InsightFaceSwap [/picsi](https://www.patreon.com/posts/introducing-ai-5-101604168) command 
<small>February 12, 2024 (November 18, 2024)</small>

---

Use this endpoint to submit the InsightFaceSwap [/picsi](https://www.patreon.com/posts/introducing-ai-5-101604168) command to directly generate a Picsi.Ai face morph by attaching a source image and target image/gif/video. The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/picsi` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/picsi**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "source_image": "Source image",
    "target_image_gif_or_video": "Target Image/GIF/Video",
    "options": "Optional parameters such as -f (Face Texturizer), -m (Retain Mouth) etc",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional, if omitted a randomly selected [configured](/docs/api-faceswap-v1/post-faceswap-account-channel) channel with available credits will be used.

- `source_image` is **required**, source image. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `target_image_gif_or_video` is **required**, target image/GIF/Video. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.  
<span class="required-input-field"><b>Important</b></span> Video currently *not* supported.

- `options` is optional, for parameters such as -f (Face Texturizer), -m (Retain Mouth), see [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349) for details.

  Options supported by **Free** version (this may not be a complete or current list, please refer to [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349)):
  * `-m` Keeps the mouth area of the target picture unchanged in the morphed result.
  * `--shut` Keeps eyes closed in your morphed results matching the closed eyes of the target face. To be used ONLY when the eyes are already closed in the target picture's face. This will NOT close eyes that are open.
  * `--ch` Corrects mismatches in chin and jawline between source and target faces.
  * `--hl` Addresses issues with bangs or low hairlines in source photos morphing incorrectly on target face.

  Options supported by **Paid** version (this may not be a complete or current list, please refer to [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349)):
  * `-f` Face Texturizer mode attempts to preserve intricate details of the target face like fine wrinkles, blemishes and freckles. 
  * `-s` Sharpen option adds clarity and definition. 
  *  `-e` Expression Matching synchronizes the expressions between your source face and the target face in the morph. This includes aspects like smiles, frowns, or any other facial expressions, aiming to retain the target face's expression in the resulting morph for enhanced realism.
  * `-e 1...1000` Expression intensity.
  * `-o` or `--oldify` Transforms faces in your images to appear older, offering an intriguing look into the future.
  * `-o 1...1000` Oldify intensity
  * `-y` Youngify is a unique feature that blends adult-like features from a source face onto young or childlike target pictures. It's designed to enhance the blend between adult features and a young-looking target face, but does not transform adults into children or make faces appear younger.
  * `-y 1...1000` Youngify intensity
  * `-a` ARTIFY enriches the morphing experience by enabling your photorealistic source face to blend seamlessly with a pre-stylized artistic target image. 
  * `-x` Xtreme specially designed for creating ultra-detailed, close-up portraits.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

If field `status` returned as `started` use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`.

Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated images.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-picsi",
    "status": "completed",
    "options": "-m",
    "source_image": { "size": 2438986, "type": "image/png" },
    "target_image_gif_or_video": { "size": 1604758, "type": "image/png" },
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id>",
    "attachments": [
      {
        "url": "<generated image_1 url>",
        "proxy_url": "<generated proxy image_1 url>",
        "width": 2048,
        "height": 2048,
        "content_type": "<generated image_1 type>",
        "id": "<Discord image_1 id>",
        "filename": "<generated image_1 name>",
        "size": 7204115
      },
      {
        "url": "<generated image_N url>",
        "proxy_url": "<generated proxy image_N url>",
        "width": 2048,
        "height": 2048,
        "content_type": "<generated image_N type>",
        "id": "<Discord image id>",
        "filename": "<generated image_N name>",
        "size": 7204115
      }
    ],
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param source_image or target_image_gif_or_video is missing or empty"
      "Param source_image or target_image_gif_or_video is not File or Blob"
      "Optional param replyUrl or replyRef is too long"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**412**
**412 Insufficient credits**

```json
{
    "error": "Not enough credits: requested 3, available 0",
    "code": 412
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/picsi](#insightfaceswap-picsi-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
1. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-picsi',
  status: 'started' | 'completed' | 'failed',
  options: string,
  source_image: { size: number, type: string },
  target_image_gif_or_video: { size: number, type: string },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  attachments: [
      {
          id: string,
          content_type: string,
          filename: string,
          url: string,
          proxy_url: string,
          size: number,
          width: number,
          height: number
      }
  ],  
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/picsi \
     -F "options=<options>" \ 
     -F 'source_image=@"<Path to the source_image>"' \
     -F 'target_image_gif_or_video=@"<Path to the target_image_gif_or_video>"' 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/picsi";
    const token = "API token";
    const options = "options";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("options", options);
    formData.append("channel", channel);

    /*
        // Example 1: Fetch image from URL
        const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
        const responseImage = await fetch(imageUrl);
        formData.append("source_image", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./target_photo.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("target_image_gif_or_video", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="target-photo-image-file" type="file"> 
        const imageFile = document.getElementById(`target-photo-image-file`);
        if (imageFile.files[0])
            formData.append("target_image_gif_or_video", imageFile.files[0]);
    */

    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/picsi"
token = "API token"
options = "options"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'options': (None, options),
    'channel': (None, channel)
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# image_content = response_image.content
# files['source_image'] = ('image.jpg', image_content, 'image/jpeg')

# # Example 2: Load image from local file
# image_file_path = "./target_photo.png"
# with open(image_file_path, 'rb') as image_file:
#     files['target_image_gif_or_video'] = ('target_photo.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid
## InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command 
---

Use this endpoint to submit the InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/saveid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/saveid**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
    "image": "Image File or Blob"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `idname` is **required**, please refer to InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) for details.

- `image` is **required**, image to upload and register for subsequent facial replacement and editing. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-saveid",
    "status": "completed",
    "idname": "me",
    "image": { "size": 1699405, "type": "image/png" },
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "idname me created",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param idname is missing or empty"
      "Required param image is missing or empty"
      "Param image is not File or Blob"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/saveid](#insightfaceswap-saveid-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-saveid',
  status: 'completed' | 'failed',
  idname: string,
  image: { size: number, type: string },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/saveid \
     -F "channel=<Discord channel id>" \
     -F 'image=@"<Path to the image>"' \
     -F "idname=<idname>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/saveid";
    const token = "API token";
    const idname = "idname";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("idname", idname);
    formData.append("channel", channel);
    /*
        // Example 1: Fetch image from URL
        const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
        const responseImage = await fetch(imageUrl);
        formData.append("image", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./my_photo.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("image", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="my-photo-image-file" type="file"> 
        const imageFile = document.getElementById(`my-photo-image-file`);
        if (imageFile.files[0])
            formData.append("image", imageFile.files[0]);
    */
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/saveid"
token = "API token"
idname = "idname"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'idname': (None, idname),
    'channel': (None, channel)
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# image_content = response_image.content
# files['image'] = ('image.jpg', image_content, 'image/jpeg')

# # Example 2: Load image from local file
# image_file_path = "./my_photo.png"
# with open(image_file_path, 'rb') as image_file:
#     files['image'] = ('my_photo.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid
## InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) command 
---

Use this endpoint to submit the InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/setid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/setid**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `idname` is **required**, please refer to InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) for details.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-setid",
    "status": "completed",
    "idname": "me",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "current idname updated",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param idname is missing or empty"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/setid](#insightfaceswap-setid-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-setid',
  status: 'completed' | 'failed',
  idname: string,
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/setid \
     -F "channel=<Discord channel id>" \
     -F "idname=<idname>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/setid";
    const token = "API token";
    const channel = "Discord channel";
    const idname = "idname";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("channel", channel);
    formData.append("idname", idname);
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/setid"
token = "API token"
channel = "Discord channel"
idname = "idname"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'channel': (None, channel),
    'idname': (None, idname)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swap ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swap
## Execute InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command immediately following by [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command.
---
<span class="required-input-field"><b>As of July 23, 2024 this endpoint is deprecated.</b></span>   
**We suggest using recently added [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) instead.**

This endpoint to execute the InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) and [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image)  command as a single call. The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

Use this endpoint if you want to swap the face from a source image, identified by `/saveid`, onto a target image designated by `/swapid`, in a single API call.

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 7 to 20 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/swap` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/swap**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "saveid_idname": "idname param to be used for /saveid command",
    "saveid_image": "Source image File or Blob",
    "swapid_idname": "idname param to be used for /swapid command",
    "swapid_image": "Target image File or Blob"
}
```
- `channel` is optional, if omitted a randomly selected [configured](/docs/api-faceswap-v1/post-faceswap-account-channel) channel with available credits will be used.

- `saveid_idname` is optional, if omitted it will default to `id`. Please refer to InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) for details.

- `saveid_image` is **required**, image to upload and register for subsequent facial replacement and editing. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `swapid_idname` is optional, if omitted it will default to `id`. Please refer to InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) for details.

- `swapid_image` is **required**, target image to be uploaded for replacing the face identified by the `idname` parameter mentioned above. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated image.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-swap",
    "status": "completed",
    "saveid_idname": "id",
    "saveid_image": { "size": 2408432, "type": "image/png" },
    "swapid_idname": "id",
    "swapid_image": { "size": 2273656, "type": "image/png" },
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "Picsi.Ai ver.2.0 [SaveID: 'id'] [<@Discord user id>] (80/200 credits used)",
    "attachments": [
      {
        "url": "<generated image url>",
        "proxy_url": "<generated proxy image url>",
        "width": 2048,
        "height": 2048,
        "content_type": "<generated image type>",
        "id": "<Discord image id>",
        "filename": "<generated image name>",
        "size": 7204115
      }
    ],
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param saveid_image is missing or empty"
      "Required param swapid_image is missing or empty"
      "Param saveid_image is not File or Blob"
      "Param swapid_image is not File or Blob"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new faceswap/swap requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-swap',
  status: 'completed' | 'failed',
  saveid_idname: string,
  saveid_image: { size: number, type: string },
  swapid_idname: string,
  swapid_image: { size: number, type: string },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  attachments: [
      {
          id: string,
          content_type: string,
          filename: string,
          url: string,
          proxy_url: string,
          size: number,
          width: number,
          height: number
      }
  ],  
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/swap \
     -F "channel=<Discord channel id>" \
     -F 'saveid_image=@"<Path to the image>"' \
     -F "saveid_idname=<idname>" \ 
     -F 'swapid_image=@"<Path to the image>"' \
     -F "swapid_idname=<idname>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/swap";
    const token = "API token";
    const saveid_idname = "saveid_idname";
    const swapid_idname = "swapid_idname";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("saveid_idname", idname);
    formData.append("swapid_idname", idname);
    formData.append("channel", channel);
    /*
        // Example 1: Fetch image from URL
        const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
        const responseImage = await fetch(imageUrl);
        formData.append("image", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./target_photo.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("image", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="target-photo-image-file" type="file"> 
        const imageFile = document.getElementById(`target-photo-image-file`);
        if (imageFile.files[0])
            formData.append("image", imageFile.files[0]);
    */
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/swap"
token = "API token"
saveid_idname = "saveid_idname"
swapid_idname = "swapid_idname"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'saveid_idname': (None, saveid_idname),
    'swapid_idname': (None, swapid_idname),
    'channel': (None, channel)
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# image_content = response_image.content
# files['image'] = ('image.jpg', image_content, 'image/jpeg')

# # Example 2: Load image from local file
# image_file_path = "./target_photo.png"
# with open(image_file_path, 'rb') as image_file:
#     files['image'] = ('target_photo.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid
## InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command 
<small>February 12, 2024 (November 18, 2024)</small>

---

Use this endpoint to submit the InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). 

This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel).

It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/swapid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v1/faceswap/swapid**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
    "image": "Image File or Blob"
}
```
- `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `idname` is **required**, please refer to InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) for details.

- `image` is **required**, target image to be uploaded for replacing the face identified by the `idname` parameter mentioned above. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated image.

```json
{
    "jobid": "<jobid>",
    "verb": "faceswap-swapid",
    "status": "completed",
    "idname": "me",
    "image": { "size": 1699405, "type": "image/png" },
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "Picsi.Ai ver.2.0 [SaveID: 'me'] [<@Discord user id>] (79/200 credits used)",
    "attachments": [
      {
        "url": "<generated image url>",
        "proxy_url": "<generated proxy image url>",
        "width": 2048,
        "height": 2048,
        "content_type": "<generated image type>",
        "id": "<Discord image id>",
        "filename": "<generated image name>",
        "size": 7204115
      }
    ],
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "Required param idname is missing or empty"
      "Required param image is missing or empty"
      "Param image is not File or Blob"
      "Optional param replyRef is too long"
      "Optional param replyUrl is too long"
      "Required param channel is missing or empty"
      "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**412**
**412 Insufficient credits**

```json
{
    "error": "Not enough credits: requested 3, available 0",
    "code": 412
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [faceswap/swapid](#insightfaceswap-swapid-command) requests. 
```json
{
    "error": "Unable to lock Discord after <attempts> attempts",
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'faceswap-swapid',
  status: 'completed' | 'failed',
  idname: string,
  image: { size: number, type: string },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by InsightFaceSwap 
  attachments: [
      {
          id: string,
          content_type: string,
          filename: string,
          url: string,
          proxy_url: string,
          size: number,
          width: number,
          height: number
      }
  ],  
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/swapid \
     -F "channel=<Discord channel id>" \
     -F 'image=@"<Path to the image>"' \
     -F "idname=<idname>" 
```

**JavaScript**
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/faceswap/swapid";
    const token = "API token";
    const idname = "idname";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("idname", idname);
    formData.append("channel", channel);
    /*
        // Example 1: Fetch image from URL
        const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
        const responseImage = await fetch(imageUrl);
        formData.append("image", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./target_photo.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("image", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="target-photo-image-file" type="file"> 
        const imageFile = document.getElementById(`target-photo-image-file`);
        if (imageFile.files[0])
            formData.append("image", imageFile.files[0]);
    */
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()

```

**Python**
``` python
import requests

api_url = "https://api.useapi.net/v1/faceswap/swapid"
token = "API token"
idname = "idname"
channel = "Discord channel"

headers = {
    'Authorization': f'Bearer {token}'
}

files = {
    'idname': (None, idname),
    'channel': (None, channel)
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# image_content = response_image.content
# files['image'] = ('image.jpg', image_content, 'image/jpeg')

# # Example 2: Load image from local file
# image_file_path = "./target_photo.png"
# with open(image_file_path, 'rb') as image_file:
#     files['image'] = ('target_photo.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-faceswap-v1/setup-multiple-faceswap-accounts ===
Document URL: https://useapi.net/docs/api-faceswap-v1/setup-multiple-faceswap-accounts
## How to use multiple InsightFaceSwap accounts 
Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account). You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot.

To take advantage of saved configurations and account load balancing, please follow these simple steps:
- Gather your InsightFaceSwap account(s) information as outlined at [Setup InsightFaceSwap](/docs/start-here/setup-faceswap).
- Post your configuration(s) using the [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel) endpoint.

To see all your currently configured InsightFaceSwap accounts, please use the [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) endpoint.

Feel free to [reach out to us](/docs/support) if you have any questions or concerns.

=== URL: https://useapi.net/docs/start-here/setup-google-flow ===
Document URL: https://useapi.net/docs/start-here/setup-google-flow
# <img src="/assets/images/google-flow.svg" style="height:1em;vertical-align: middle;"> Google Flow
<small>November 17, 2025 (April 13, 2026)</small>

## Table of contents
<small>Approximately 15 minutes to complete setup steps.</small>  

---
> This is the setup guide for [Google Flow API](/docs/api-google-flow-v1). An active [Google](https://accounts.google.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

### Automated setup (recommended)

Use our guided browser setup to configure your account automatically — no DevTools or cookie copying needed. Enter your API token, log in with Google in the remote browser, and your account is ready.

[Open automated setup](/assets/setup-browser/google-flow.html){: .btn .btn-primary .fs-4 }

<small>Prefer manual setup? Continue with the steps below.</small>

---

[Google Flow](https://labs.google/fx/tools/flow) creates cinematic AI clips with [Veo](https://aistudio.google.com/models/veo-3), images with [Imagen 4](https://deepmind.google/technologies/imagen-3/) and [Nano Banana / Gemini 2.5 Flash Image](https://deepmind.google/technologies/gemini/flash/).

### Create a dedicated Gmail account

⚠️ **Use a dedicated Gmail account for this API - do NOT use your personal Gmail account.**

If you already have a dedicated Gmail account for AI/API services, you can use that. Otherwise, create a new one.

When creating a new account:
1. Enable [2-Step Verification](https://support.google.com/accounts/answer/185839)
2. Use [Google Authenticator](https://support.google.com/accounts/answer/1066447) for verification codes

### Clear all browser cookies

⚠️ **Do NOT use Google Chrome.** Google's integration with Chrome will interfere with cookie extraction.

**Use one of these browsers instead:**
- [Opera](https://www.opera.com/) ← Recommended (has built-in VPN)
- [Brave](https://brave.com/)
- [Ungoogled Chromium](https://github.com/ungoogled-software/ungoogled-chromium)

If using Opera, enable VPN and set region to Americas.

**You must clear ALL cookies before proceeding** to start with a fresh session.

Open browser settings and select `Delete browsing data...` <span style="color: red;">`1`</span>

![](/assets/images/google-flow-setup-1.jpg)

Select time range to be `All time` <span style="color: red;">`1`</span> and check `Cookies and other site data` <span style="color: red;">`2`</span>, click `Delete data` <span style="color: red;">`3`</span>

![](/assets/images/google-flow-setup-2.jpg)

### Navigate to Google Flow and login with your Gmail account

Navigate to [https://labs.google/fx/tools/flow](https://labs.google/fx/tools/flow) and click on `Sign in with Google` button <span style="color: red;">`1`</span>

![](/assets/images/google-flow-setup-3.jpg)

Enter your Google email created earlier <span style="color: red;">`1`</span>

![](/assets/images/google-flow-setup-4.jpg)

Enter 2-Step Verification code <span style="color: red;">`1`</span>

⚠️ **You MUST check `Don't ask again on this device`** <span style="color: red;">`2`</span> - skipping this will break the API session.

![](/assets/images/google-flow-setup-5.jpg)

Once successfully logged in you should see `New project` button

![](/assets/images/google-flow-setup-6.jpg)

### Navigate to Google Account 

Navigate to [https://myaccount.google.com/](https://myaccount.google.com/)

![](/assets/images/google-flow-setup-7.jpg)

### Copy `https://accounts.google.com/` cookies

1. **Open Developer Tools:** right-click anywhere on page → select `Inspect` (or press `F12`)

![](/assets/images/google-flow-setup-8.jpg)

2. **Go to Application tab** <span style="color: red;">`1`</span>
3. **Select Cookies** → `https://accounts.google.com/` <span style="color: red;">`2`</span>
4. **Select all cookies** in the right panel (`Ctrl+A`) and **copy** (`Ctrl+C`) <span style="color: red;">`3`</span>

![](/assets/images/google-flow-setup-9.jpg)

Your copied cookies will look similar to this (values redacted):

![](/assets/images/google-flow-setup-10.jpg)

### Verify and add account

Use the form below to verify your cookies and add your Google Flow account.

Select **Add Account** to complete setup, or **Verify** to test your cookies first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) directly.

⚠️ **CRITICAL — Do this immediately after adding your account:**

1. Open a new empty tab
2. Close all other tabs
3. [Clear all browser cookies](#clear-all-browser-cookies)
4. **Do NOT restart the browser**

⚠️ **The API now manages this Google account session.**

Do NOT access this Google account via AI Studio or Google Flow directly (browser or any other means). Using the same account through both the API and direct access will break the session and require you to redo this entire setup.

<script>
  async function apiTestAccountGoogleFlow(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-GoogleFlow-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let cookies = document.getElementById(`post-accounts-GoogleFlow-cookies`)?.value;

      const body = { cookies };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/google-flow/accounts`, 'post-accounts-GoogleFlow', data);
  }
</script>

<form id="post-accounts-GoogleFlow" onsubmit="apiTestAccountGoogleFlow(document.getElementById('post-accounts-GoogleFlow-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-GoogleFlow-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-GoogleFlow-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-GoogleFlow-cookies"><span>cookies</span>
        <textarea id="post-accounts-GoogleFlow-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea>
      </label>
      <label for="post-accounts-GoogleFlow-action"><span>action</span>
        <select id="post-accounts-GoogleFlow-action" class="input-element">
          <option value="verify">Verify — test cookies only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-GoogleFlow-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-GoogleFlow-response" class="response-placeholder visible-false"></div>

### Configure Captcha Providers

Image and video generation requires reCAPTCHA v3 Enterprise solving.

**Users receive 100 free captcha credits** when adding their first Google Flow account. These credits are used automatically, so you can start generating images and videos right away without configuring any provider. Check your remaining credits via [GET /accounts/captcha-providers](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers).

After free credits are exhausted, you must configure at least one provider's API key before using [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos).

**Supported Providers:**

| Provider | Cost per 1K | Avg Solve Time | Website |
|----------|-------------|----------------|---------|
| **AntiCaptcha** | ~$2.00 | ~8-12s | [anti-captcha.com](https://anti-captcha.com/) |
| **EzCaptcha** | ~$2.50 | ~8-12s | [ez-captcha.com](https://www.ez-captcha.com/) |
| **CapSolver** | ~$3.00 | ~8-12s | [capsolver.com](https://www.capsolver.com/) — use promo code `useapi` for 8% discount |
| **YesCaptcha** | varies | ~8-12s | [yescaptcha.com](https://yescaptcha.com/) |
| **SolveCaptcha** | ~$0.80 | ~30-60s | [solvecaptcha.com](https://solvecaptcha.com/) |
| **2Captcha** | ~$2.99 | ~30-60s | [2captcha.com](https://2captcha.com/) |

**Setup Steps:**

1. Create an account with one or more providers above
2. Purchase credits and obtain your API key from the provider's dashboard
3. Configure your API key(s) using [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)

**Tips:**
- Use [GET /accounts/captcha-stats?anonymized=true](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) to compare success rates across providers and choose the best one for your needs. Note that provider performance may vary over time.
- Configure multiple providers for redundancy (if one fails or returns rejected tokens, the API automatically retries with the next provider)
- Each image/video generation attempt requires one captcha solve (~$0.80-$3.00 per 1,000 generations)

=== URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email ===
Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email
## Delete Account Configuration
<small>November 17, 2025</small>

---

Delete a configured Google Flow account. This removes the account from your configuration and cancels any scheduled refresh operations.

**Warning:** This action cannot be undone. You will need to reconfigure the account using [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) if you want to use it again.
> **https://api.useapi.net/v1/google-flow/accounts/`email`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `email` is **required**. The email address of the Google Flow account to delete (URL-encoded if necessary).

### Responses

**200**
**200 OK**

Account deleted successfully.

```json
{
  "message": "Google Flow account john@gmail.com deleted"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const email = 'john@gmail.com';

const response = await fetch(
  `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(email)}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const result = await response.json();
console.log('Delete result:', result);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
email = 'john@gmail.com'

headers = {'Authorization': f'Bearer {token}'}

response = requests.delete(
    f'https://api.useapi.net/v1/google-flow/accounts/{quote(email)}',
    headers=headers
)

print('Delete result:', response.json())
```

### Try It

<script>
  async function apiExecuteDeleteGoogleFlowAccountsEmail() {
    const tokenElement = document.getElementById('input-token');
    const emailElement = document.getElementById('input-email');

    const data = {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(emailElement.value)}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-email"><span>email<small> (required)</small></span>
        <input id="input-email" type="text" class="input-element" required aria-required="true" placeholder="john@gmail.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteGoogleFlowAccountsEmail()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers
## Get Captcha Providers
<small>December 23, 2025 (February 18, 2026)</small>

---

Retrieve configured captcha provider API keys (masked for security).
> **https://api.useapi.net/v1/google-flow/accounts/captcha-providers**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

Returns masked keys for all configured providers.

**With providers configured:**
```json
{
  "CapSolver": "abc12…",
  "AntiCaptcha": "def34…"
}
```

**No providers configured (shows free credits if available):**
```json
{
  "freeCaptchaCredits": 100
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model

```typescript
{ // TypeScript, all fields are optional
  CapSolver?: string          // Masked API key or omitted if not configured
  AntiCaptcha?: string        // Masked API key or omitted if not configured
  YesCaptcha?: string         // Masked API key or omitted if not configured
  CapMonster?: string         // Masked API key or omitted if not configured
  SolveCaptcha?: string       // Masked API key or omitted if not configured
  '2Captcha'?: string         // Masked API key or omitted if not configured
  EzCaptcha?: string          // Masked API key or omitted if not configured
  freeCaptchaCredits?: number // Remaining free credits (only shown when no providers configured)
}
```

**Note:** `freeCaptchaCredits` is only included in the response when:
- No captcha providers are configured, AND
- The user has remaining free credits (> 0)

### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-providers"
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers';
const token = 'YOUR_API_TOKEN';

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const result = await response.json();
console.log('Configured providers:', result);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers'
token = 'YOUR_API_TOKEN'

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(apiUrl, headers=headers)
print(response.status_code, response.json())
```

### Try It

<script>
  async function apiTestCaptchaProvidersGet() {
      const data = {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${document.getElementById('get-captcha-providers-api_token').value}`
        }
      };

      await apiExecute('https://api.useapi.net/v1/google-flow/accounts/captcha-providers', 'get-captcha-providers', data);
  }
</script>

<form id="get-captcha-providers" onsubmit="return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="get-captcha-providers-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="get-captcha-providers-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
    </div>
    <button id="get-captcha-providers-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestCaptchaProvidersGet()">Go</button>
  </div>
</form>

<div id="get-captcha-providers-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats
## Get Captcha Statistics
<small>February 4, 2026 (May 18, 2026)</small>

---

Query captcha solving statistics for your account. Returns detailed information about captcha token requests and their success/failure rates. Compare success rates across all configured providers to help decide which one works best for your use case.

Use `anonymized=true` to get aggregated scores across all users and all captcha providers. This mode returns a summary only (no individual data rows) based on the last 5000 records across all accounts, giving you a broader picture of provider performance.

**Note:**
- Data latency is at least 5 minutes, but should not exceed 15 minutes.
- Data is retained for 3 months.
- Results are cached for 5 minutes.
> **https://api.useapi.net/v1/google-flow/accounts/captcha-stats**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Query Parameters

| Parameter | Required | Description |
|:----------|:---------|:------------|
| `date` | No | Date in `YYYY-MM-DD` format.<br>Defaults to today if `limit` is not specified. |
| `limit` | No | Number of records to return (max: 50000).<br>If specified, `date` filter is ignored and returns last N records across all dates. |
| `provider` | No | Filter by captcha provider.<br>Supported: `CapSolver`, `AntiCaptcha`, `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha`, `UserProvided` |
| `anonymized` | No | Set to `true` to return aggregated scores across all users and all captcha providers.<br>Returns summary only (no individual data rows).<br>Uses last 5000 records across all accounts, ignores `date`/`limit`/`provider` filters. |

### Responses

**200**
**200 OK**

Returns captcha statistics for the specified filters.

```json
{
  "date": "2026-02-03",
  "total": 42,
  "summary": {
    "from": "2026-02-03T00:05:23.000Z",
    "to": "2026-02-03T23:58:47.000Z",
    "time_span": "23 hours 53 minutes",
    "sample_size_by_provider": {
      "CapSolver": 24,
      "AntiCaptcha": 10,
      "EzCaptcha": 8
    },
    "success_rate_by_provider": {
      "CapSolver": 73.20,
      "AntiCaptcha": 80.50,
      "EzCaptcha": 68.40
    },
    "by_status_code_images": {
      "200": 69.10,
      "403": 8.50,
      "429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC": 12.30,
      "429:PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED": 4.10,
      "429:PUBLIC_ERROR_USER_REQUESTS_THROTTLED": 1.00,
      "429:PUBLIC_ERROR_USER_QUOTA_REACHED": 1.40,
      "503": 3.60
    },
    "by_status_code_videos": {
      "200": 67.50,
      "403": 17.60,
      "429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC": 8.70,
      "429:PUBLIC_ERROR_USER_REQUESTS_THROTTLED": 1.00,
      "429:PUBLIC_ERROR_USER_QUOTA_REACHED": 1.40,
      "503": 3.80
    },
    "avg_captcha_ms": 8500,
    "avg_api_ms": 1200,
    "avg_attempt": 1.2
  },
  "data": [
    {
      "timestamp": "2026-02-03T10:30:00.000Z",
      "jobId": "20260203103000123-user:123-bot:google-flow",
      "provider": "AntiCaptcha",
      "taskId": "abc123-task-id",
      "route": "post-videos",
      "statusText": "OK",
      "pageAction": "VIDEO_GENERATION",
      "error": "",
      "reason": "",
      "statusCode": 200,
      "captchaDurationMs": 8500,
      "apiDurationMs": 1200,
      "attemptNumber": 1
    }
  ]
}
```

The `summary` object provides aggregated statistics (omitted if no data).

#### Understanding the 429 buckets

Google returns `HTTP 429 RESOURCE_EXHAUSTED` in at least four known distinct situations. The `by_status_code_images` / `by_status_code_videos` summary splits 429s by their reason code so you can tell them apart — each needs a different strategy.

| Bucket key | What it means | Customer strategy |
|---|---|---|
| `429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | **Captcha-provider issue, not a useapi.net issue.** Google's reCAPTCHA Enterprise scored the token below its risk threshold — usually because the provider is overloaded or being fingerprinted by Google. Our worker has already auto-retried with fresh captcha tokens (up to `captchaRetry` attempts, default 3); this share represents requests where the retry budget exhausted. **Counts as a captcha failure in `success_rate_by_provider`** because it reflects token quality from the provider. | Spread the load across multiple captcha providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) and use `captchaOrder` on the request to cycle through them. Top up balance on existing providers (some prioritize higher-balance accounts). Short-term: wait 30-60s and retry, or bump `captchaRetry` higher. |
| `429:PUBLIC_ERROR_USER_REQUESTS_THROTTLED` | Google-side per-user concurrency limit. The captcha token was fine — this account is just sending too many requests at once. **Does NOT count as a captcha failure.** | Hold for ~hour, pause this account, retry after 10-60 minutes. Reduce parallel generations per account. |
| `429:PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED` | This account hit Google's per-model daily quota. **Does NOT count as a captcha failure.** | Hold for the day — quota resets at UTC midnight. Or switch to a different model. |
| `429:PUBLIC_ERROR_USER_QUOTA_REACHED` | This account hit its overall Google Flow quota cap — separate from per-model limits, blocks **all** models on this account. **Does NOT count as a captcha failure.** | Add more Google Flow accounts via [POST /accounts/`email`](/docs/api-google-flow-v1/post-google-flow-accounts-email) so the load is spread. Hold this specific account until the quota resets, or omit `email` to let load balancing pick a healthier account. |

#### How `success_rate_by_provider` is calculated

This is the **end-to-end captcha effectiveness** per provider — measured against Google's reCAPTCHA Enterprise evaluation, not just whether the token was syntactically accepted. Use it to compare providers and decide which to prefer, drop, or rebalance.

A row counts as a **captcha failure** when:

- HTTP `403` — token was rejected outright (`PERMISSION_DENIED`)
- HTTP `429` with reason `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` — Google's response literally says `"reCAPTCHA evaluation failed"`. The token was technically valid but scored too low. This typically means the provider is overloaded or being fingerprinted by Google.

The other 429 reasons (`PER_MODEL_DAILY_QUOTA_REACHED`, `USER_REQUESTS_THROTTLED`, `USER_QUOTA_REACHED`) are NOT counted as captcha failures because they are account-level limits independent of token quality. HTTP `503` is also excluded (Google-side outage, unrelated to the provider).

**Actionable reading:** if one provider has noticeably lower `success_rate_by_provider` than others over the same period, its tokens are scoring poorly with reCAPTCHA Enterprise. Either drop that provider from your rotation, reduce its weight in `captchaOrder`, or top up its balance (some providers prioritize higher-balance accounts when issuing fresh proxies/IPs).

#### How `by_status_code_images` / `by_status_code_videos` are aggregated

The status distribution shows **customer-facing final outcomes per `jobId`**, not per attempt. A request that internally retried 5 times before succeeding contributes a single `"200"` to the bucket, not five entries. This makes the distribution a true outcome map.

A `429:<reason>` bucket therefore counts only requests where our internal retry budget was exhausted before resolving the condition.

**400**
**400 Bad Request**

Missing or invalid parameters.

```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model

```typescript
// Response structure
{
  date?: string                  // Date filter applied (YYYY-MM-DD)
  limit?: number                 // Limit filter applied
  provider?: string              // Provider filter applied
  total: number                  // Total records returned
  summary?: {                    // Aggregated statistics (omitted if no data)
    from: string                 // Earliest timestamp (ISO 8601)
    to: string                   // Latest timestamp (ISO 8601)
    time_span: string            // Human readable duration (e.g., "2 days 5 hours")
    sample_size_by_provider: Record<string, number>    // Records per provider across ALL attempts (excludes 503)
    success_rate_by_provider: Record<string, number>  // Captcha success rate % per provider. Failures: 403 (token rejected) AND 429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC (token scored too low by reCAPTCHA Enterprise). Other 429 reasons are NOT counted. (excludes 503)
    by_status_code_images: Record<string, number>     // % per customer-facing final-attempt outcome for IMAGE. 429s split by reason — e.g. "429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC"
    by_status_code_videos: Record<string, number>     // Same as by_status_code_images but for VIDEO
    avg_captcha_ms: number       // Average captcha solve time in ms
    avg_api_ms: number           // Average API call time in ms
    avg_attempt: number          // Average attempt number
  }
  data: Array<{
    timestamp: string            // ISO 8601 timestamp
    jobId: string                // Job identifier
    provider: string             // Captcha provider used (CapSolver, AntiCaptcha, YesCaptcha, CapMonster, SolveCaptcha, 2Captcha, EzCaptcha, UserProvided)
    taskId: string               // Provider's task ID
    route: string                // API route (post-videos, post-images, etc.)
    statusText: string           // HTTP status text (OK, Forbidden, NetworkError)
    pageAction: string           // reCAPTCHA action (VIDEO_GENERATION, IMAGE_GENERATION)
    error: string                // Error message (empty on success)
    reason: string               // Google ErrorInfo.reason — e.g. PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC (empty for non-Google errors or successful submits)
    statusCode: number           // HTTP status code (200, 403, 429, 0 for network errors)
    captchaDurationMs: number    // Captcha solve duration in ms
    apiDurationMs: number        // API call duration in ms
    attemptNumber: number        // Attempt number (1 = first try, 2+ = retry)
  }>
}
```

### Examples

**Curl**
``` bash
# Today's stats
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-stats"

# Specific date
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?date=2026-02-01"

# Last 1000 records
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?limit=1000"

# Filter by provider
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?provider=AntiCaptcha"

# Aggregated scores across all users and providers (summary only)
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?anonymized=true"
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats';
const token = 'YOUR_API_TOKEN';

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const stats = await response.json();
console.log(`Total records: ${stats.total}`);
console.log(`Success rates:`, stats.summary?.success_rate_by_provider);
console.log('Data:', stats.data);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats'
token = 'YOUR_API_TOKEN'

headers = {
    'Authorization': f'Bearer {token}'
}

# Today's stats
response = requests.get(apiUrl, headers=headers)
stats = response.json()
print(f"Total records: {stats['total']}")
print(f"Success rates: {stats.get('summary', {}).get('success_rate_by_provider')}")

# Filter by provider
response = requests.get(
    apiUrl,
    params={'provider': 'AntiCaptcha'},
    headers=headers
)
```

### Try It

<script src="/assets/js/captcha-stats-visualizer.js"></script>
<script>
  async function apiExecuteInput() {
    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${document.getElementById('input-token').value}`
      }
    };

    const inputs = document.querySelectorAll('.input-query-param');
    const params = new URLSearchParams();

    inputs.forEach(input => {
        const id = input.id;
        const value = input.value?.trim();
        if (id.startsWith('input-') && value !== '' && value !== undefined) {
            const key = id.replace('input-', '');
            params.append(key, value);
        }
    });

    const url = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats' +
                (params.toString() ? '?' + params.toString() : '');

    const vizContainer = document.getElementById('input-stats-viz');
    if (vizContainer) {
      vizContainer.innerHTML = '';
      vizContainer.style.display = 'none';
    }

    const status = await apiExecute(url, 'input', data);

    if (status === 200) {
      try {
        const jsonText = document.getElementById('input-response-json').textContent;
        const result = JSON.parse(jsonText);
        if (result && result.data && Array.isArray(result.data)) {
          await displayCaptchaStatsResult(result, 'input-stats-viz');
        }
      } catch (e) { }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="input-date"><span>date<small> (YYYY-MM-DD)</small></span>
        <input id="input-date" type="text" class="input-element input-query-param" oninput="this.size = this.value.length">
      </label>
      <label for="input-limit"><span>limit<small> (max 50000)</small></span>
        <input id="input-limit" type="text" class="input-element input-query-param" oninput="this.size = this.value.length">
      </label>
      <label for="input-provider"><span>provider</span>
        <select id="input-provider" class="input-element input-query-param">
          <option value="">All providers</option>
          <option value="CapSolver">CapSolver</option>
          <option value="AntiCaptcha">AntiCaptcha</option>
          <option value="YesCaptcha">YesCaptcha</option>
          <option value="CapMonster">CapMonster</option>
          <option value="SolveCaptcha">SolveCaptcha</option>
          <option value="2Captcha">2Captcha</option>
          <option value="EzCaptcha">EzCaptcha</option>
          <option value="UserProvided">UserProvided</option>
        </select>
      </label>
      <label for="input-anonymized"><span>anonymized</span>
        <select id="input-anonymized" class="input-element input-query-param">
          <option value="">No</option>
          <option value="true">All users, all providers (last 5K, summary only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteInput()">Go</button>
  </div>
</form>

<div id="input-stats-viz" style="display:none;"></div>
<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-email ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-email
## Get Account Configuration
<small>November 17, 2025 (April 14, 2026)</small>

---

Get configuration details for a specific Google Flow account, including health status, credits information, and available video models.
> **https://api.useapi.net/v1/google-flow/accounts/`email`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `email` is **required**. The email address of the Google Flow account to query (URL-encoded if necessary).

### Responses

**200**
**200 OK**

Account configuration found and returned with health status.

```json
{
  "created": "2025-11-10T12:00:00.000Z",
  "accountCookies": [
    {
      "name": "HSID",
      "value": "AYQ...(redacted)",
      "domain": ".google.com",
      "path": "/",
      "expires": "2027-11-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "sessionCookies": [
    {
      "name": "__Host-GAPS",
      "value": "1:eJy...(redacted)",
      "domain": "labs.google",
      "path": "/",
      "expires": "2025-12-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "sessionData": {
    "user": {
      "name": "John Doe",
      "email": "jo***@gmail.com",
      "image": "https://lh3.googleusercontent.com/a/..."
    },
    "expires": "2025-11-11T12:00:00.000Z",
    "access_token": "ya29.a0A...(redacted)"
  },
  "project": {
    "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d",
    "projectTitle": "Nov 11 - 02:56"
  },
  "nextRefresh": {
    "messageId": "msg-abc123",
    "scheduledFor": "2025-11-11T11:00:00.000Z"
  },
  "health": "OK",
  "credits": {
    "credits": 1250,
    "userPaygateTier": "PAYGATE_TIER_TWO"
  },
  "models": {
    "videoModels": [
      {
        "key": "veo_3_1_t2v",
        "displayName": "Veo 3.1 - Quality",
        "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE"],
        "capabilities": ["VIDEO_MODEL_CAPABILITY_AUDIO", "VIDEO_MODEL_CAPABILITY_TEXT"],
        "videoLengthSeconds": 8,
        "videoGenerationTimeSeconds": 240,
        "creditCost": 100,
        "framesPerSecond": 24,
        "paygateTier": "PAYGATE_TIER_TWO",
        "accessType": "MODEL_ACCESS_TYPE_GENERAL",
        "modelAccessInfo": {},
        "modelMetadata": {
          "veoModelName": "Beta Audio"
        }
      },
      {
        "key": "veo_3_1_t2v_lite_low_priority",
        "displayName": "Veo 3.1 - Lite [Lower Priority]",
        "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE", "VIDEO_ASPECT_RATIO_PORTRAIT"],
        "capabilities": ["VIDEO_MODEL_CAPABILITY_AUDIO", "VIDEO_MODEL_CAPABILITY_TEXT"],
        "videoLengthSeconds": 8,
        "videoGenerationTimeSeconds": 110,
        "creditCost": 0,
        "framesPerSecond": 24,
        "paygateTier": "PAYGATE_TIER_TWO",
        "accessType": "MODEL_ACCESS_TYPE_GENERAL",
        "modelAccessInfo": {},
        "modelMetadata": {
          "veoModelName": "Beta Audio"
        }
      }
    ]
  }
}
```

**Note:** Sensitive values (cookie values, access tokens) are redacted for security. Email addresses are partially masked.

The `credits` and `models` fields are only included when `health` is `"OK"`.

**Free models on Ultra:** For accounts with Google AI Ultra subscription ([PAYGATE_TIER_TWO](https://one.google.com/ai)), video models with `creditCost: 0` are free to generate. These are the lower-priority variants — keys ending in `_low_priority` or `_relaxed` (e.g. `veo_3_1_t2v_lite_low_priority`, `veo_3_1_t2v_fast_ultra_relaxed`). Keys ending in `_ultra` (without `_relaxed`) are discounted but not free — they typically cost 10 credits per generation.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Google Flow account email@example.com not found"
}
```

### Model
```typescript
{
  created: string              // ISO 8601 timestamp
  accountCookies: Array<{
    name: string
    value: string              // Redacted
    domain: string
    path: string
    expires: string | number
    httpOnly: boolean
    secure: boolean
    sameSite: 'Lax' | 'Strict' | 'None'
  }>
  sessionCookies: Array<{      // Same structure
    name: string
    value: string              // Redacted
    domain: string
    path: string
    expires: string | number
    httpOnly: boolean
    secure: boolean
    sameSite: 'Lax' | 'Strict' | 'None'
  }>
  sessionData: {
    user: {
      name: string
      email: string            // Partially masked
      image: string
    }
    expires: string            // ISO 8601 timestamp
    access_token: string       // Redacted
  }
  project: {
    projectId: string
    projectTitle: string
  }
  nextRefresh: {
    messageId: string
    scheduledFor: string       // ISO 8601 timestamp
  }
  health: string               // "OK" | "<error>"
  credits?: {                  // Only present when health is "OK"
    credits: number
    userPaygateTier: string    // "PAYGATE_TIER_ONE" | "PAYGATE_TIER_TWO"
  }
  models?: {                   // Only present when health is "OK"
    videoModels: Array<{
      key: string              // Model identifier (e.g., "veo_3_1_t2v_fast_ultra")
      displayName: string      // "Veo 3.1 - Fast" | "Veo 3.1 - Quality" | "Veo 3.1 - Lite" | "Veo 3.1 - Lite [Lower Priority]" | ...
      supportedAspectRatios: string[]
      capabilities: string[]   // e.g., ["VIDEO_MODEL_CAPABILITY_TEXT", "VIDEO_MODEL_CAPABILITY_AUDIO"]
      videoLengthSeconds: number
      videoGenerationTimeSeconds?: number
      creditCost: number       // Credits charged per generation. 0 for free Ultra-only variants (`_low_priority`, `_relaxed`).
      framesPerSecond: number
      paygateTier: string      // "PAYGATE_TIER_ONE" | "PAYGATE_TIER_TWO"
      accessType: string
      modelAccessInfo: object
      modelMetadata: object
    }>
  }
  error?: string               // Error message
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const email = 'john@gmail.com';

const response = await fetch(
  `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(email)}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const accountConfig = await response.json();
console.log('Account config:', accountConfig);
console.log('Health:', accountConfig.health);
console.log('Credits:', accountConfig.credits);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
email = 'john@gmail.com'

headers = {'Authorization': f'Bearer {token}'}

response = requests.get(
    f'https://api.useapi.net/v1/google-flow/accounts/{quote(email)}',
    headers=headers
)

account_config = response.json()
print('Account config:', account_config)
print('Health:', account_config.get('health'))
print('Credits:', account_config.get('credits'))
```

### Try It

<script>
  async function apiExecuteGetGoogleFlowAccountsEmail() {
    const tokenElement = document.getElementById('input-token');
    const emailElement = document.getElementById('input-email');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(
      `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(emailElement.value)}`,
      'input',
      data
    );
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-email"><span>email<small> (required)</small></span>
        <input id="input-email" type="text" class="input-element" required aria-required="true" placeholder="john@gmail.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAccountsEmail()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts
## List All Configured Accounts
<small>November 17, 2025 (December 1, 2025)</small>

---

List all configured Google Flow accounts.

To get a specific account use [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email).
> **https://api.useapi.net/v1/google-flow/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

Returns a map of all configured accounts, keyed by email address.

```json
{
  "a***@gmail.com": {
    "created": "2025-11-09T22:02:04.802Z",
    "health": "OK",
    "nextRefresh": {
      "scheduledFor": "2025-12-01T11:46:01.000Z"
    },
    "project": {
      "projectId": "a7e08e13-a6ea-4945-9841-cb4147e4f024",
      "projectTitle": "Nov 11 - 02:56"
    },
    "sessionData": {
      "expires": "2025-12-01T12:46:01.000Z"
    }
  },
  "b***@gmail.com": {
    "created": "2025-11-10T02:56:58.864Z",
    "health": "OK",
    "nextRefresh": {
      "scheduledFor": "2025-12-01T09:13:16.000Z"
    },
    "project": {
      "projectId": "47050a10-06f4-4469-8ab0-6d294c703508",
      "projectTitle": "Nov 11 - 02:56"
    },
    "sessionData": {
      "expires": "2025-12-01T10:13:16.000Z"
    }
  }
}
```

If no accounts are configured, returns an empty object `{}`.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model
```typescript
// Map of email to account summary
{
  [email: string]: {
    health: string               // "OK" | "<error>"
    error?: string               // Error message if health check failed
    created?: string             // ISO 8601 timestamp
    sessionData?: {
      expires: string            // ISO 8601 timestamp
    }
    project?: {
      projectId: string
      projectTitle: string
    }
    nextRefresh?: {
      scheduledFor: string       // ISO 8601 timestamp
    }
  }
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v1/google-flow/accounts', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const accounts = await response.json();
console.log('Configured accounts:', accounts);
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {'Authorization': f'Bearer {token}'}

response = requests.get('https://api.useapi.net/v1/google-flow/accounts', headers=headers)
print('All accounts:', response.json())
```

### Try It

<script>
  async function apiExecuteGetGoogleFlowAccounts() {
    const tokenElement = document.getElementById('input-token');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute('https://api.useapi.net/v1/google-flow/accounts', 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAccounts()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs-jobid ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs-jobid
## Retrieve Job Status
<small>November 17, 2025 (May 11, 2026)</small>

---

Retrieve the status and details of a specific image or video generation job by its job ID.

This endpoint is particularly useful when using [async mode](/docs/api-google-flow-v1/post-google-flow-videos) for video generation, or when tracking job progress via webhooks using the `replyUrl` parameter.

To get load balancing statistics across all jobs, use [GET /jobs](/docs/api-google-flow-v1/get-google-flow-jobs).
> **https://api.useapi.net/v1/google-flow/jobs/`jobId`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobId` is **required**, the unique job identifier returned from [POST /images](/docs/api-google-flow-v1/post-google-flow-images) or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos).

### Responses

**200**
**200 OK**

Returns the job record with current status and details.

**Video job (completed):**

```json
{
  "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow",
  "type": "video",
  "status": "completed",
  "created": "2025-11-17T12:34:56.789Z",
  "updated": "2025-11-17T12:37:23.456Z",
  "request": {
    "email": "jo***@gmail.com",
    "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
    "model": "veo-3.1-fast",
    "aspectRatio": "landscape",
    "count": 2,
    "seed": 123456,
    "async": true,
    "replyUrl": "https://your-domain.com/webhook"
  },
  "response": {
    "operations": [
      {
        "operation": {
          "name": "d00af...redacted...6f7a"
        },
        "sceneId": "abc123...",
        "status": "VIDEO_GENERATION_STATUS_SUCCEEDED",
        "video": {
          "uri": "https://storage.googleapis.com/...",
          "seed": 123456,
          "mediaGenerationId": "CAUSJ...redacted...OWQ5ZA",
          "fifeUrl": "https://storage.googleapis.com/...",
          "servingBaseUri": "https://lh3.googleusercontent.com/..."
        }
      }
    ],
    "captcha": {
      "service": "AntiCaptcha",
      "taskId": "abc123...",
      "durationMs": 3500,
      "attempts": [
        {
          "service": "AntiCaptcha",
          "taskId": "abc123...",
          "durationMs": 3500,
          "success": true
        }
      ]
    }
  }
}
```

**Image job (completed):**

```json
{
  "jobid": "j1731859345678i-u12345-email:an***@gmail.com-bot:google-flow",
  "type": "image",
  "status": "completed",
  "created": "2025-11-17T12:45:12.345Z",
  "updated": "2025-11-17T12:45:34.678Z",
  "request": {
    "email": "an***@gmail.com",
    "prompt": "A serene mountain landscape at sunset with vibrant colors",
    "model": "imagen-4",
    "aspectRatio": "landscape",
    "count": 4,
    "replyUrl": "https://your-domain.com/webhook",
    "replyRef": "custom-reference-123"
  },
  "response": {
    "media": [
      {
        "name": "…redacted…",
        "image": {
          "generatedImage": {
            "seed": 987654,
            "mediaGenerationId": "user:12345…redacted…",
            "fifeUrl": "https://storage.googleapis.com/...",
            "prompt": "A serene mountain landscape at sunset with vibrant colors"
          }
        }
      }
    ],
    "captcha": {
      "service": "AntiCaptcha",
      "taskId": "abc123...",
      "durationMs": 3200,
      "attempts": [
        {
          "service": "AntiCaptcha",
          "taskId": "abc123...",
          "durationMs": 3200,
          "success": true
        }
      ]
    }
  }
}
```

**Job failed:**

```json
{
  "jobid": "j1731859567890i-u12345-email:an***@gmail.com-bot:google-flow",
  "type": "image",
  "status": "failed",
  "created": "2025-11-17T13:00:12.345Z",
  "updated": "2025-11-17T13:00:45.678Z",
  "request": {
    "email": "an***@gmail.com",
    "prompt": "Generate an image",
    "model": "nano-banana"
  },
  "error": "API error: 500",
  "code": 500,
  "response": {
    "error": {
      "code": 500,
      "message": "Internal error encountered.",
      "status": "INTERNAL"
    }
  }
}
```

**400**
**400 Bad Request**

Invalid job ID format.

```json
{
  "error": "Invalid job ID format"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**403**
**403 Forbidden**

Job belongs to a different user.

```json
{
  "error": "Access denied - job belongs to different user"
}
```

**404**
**404 Not Found**

Job not found in database.

```json
{
  "error": "Job not found"
}
```

**410**
**410 Gone**

Job has expired (jobs are retained for 7 days).

```json
{
  "error": "Job has expired"
}
```

### Model

**Video Job**

Video generation job structure.

```typescript
{
  jobid: string                       // Unique job identifier
  type: 'video'                       // Job type
  status: 'created' | 'started' | 'completed' | 'failed'
  created: string                     // ISO 8601 creation timestamp
  updated?: string                    // ISO 8601 last update timestamp

  request: {
    email?: string
    prompt: string
    model?: 'veo-3.1-quality' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3.1-lite-low-priority'
    aspectRatio?: 'landscape' | 'portrait' | 'square'
    count?: number                    // 1-4
    seed?: number
    startImage?: string               // mediaGenerationId for I2V mode
    endImage?: string                 // mediaGenerationId for I2V-FL mode
    referenceImage_1?: string         // mediaGenerationId for R2V mode
    referenceImage_2?: string         // mediaGenerationId for R2V mode
    referenceImage_3?: string         // mediaGenerationId for R2V mode
    async?: boolean                   // Fire-and-forget mode
    replyUrl?: string                 // Webhook URL for callbacks
    replyRef?: string                 // Custom reference for callbacks
  }

  response?: {
    operations: Array<{
      operation: {
        name: string
        error?: {                     // Present when operation failed
          code: number
          message: string
        }
        metadata?: {                  // Present when completed
          '@type': string
          name: string
          video: {
            seed: number
            mediaGenerationId: string
            prompt: string
            fifeUrl: string           // Signed video URL (MP4, valid ~24h)
            mediaVisibility: string
            servingBaseUri: string    // Signed thumbnail URL (JPEG, valid ~24h)
            model: string             // veo_3_1_t2v | veo_3_1_i2v | veo_3_1_i2v_fl | veo_3_0_r2v
            isLooped: boolean
            aspectRatio: string       // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
          }
        }
      }
      sceneId: string
      mediaGenerationId?: string      // Present when completed
      status: string                  // MEDIA_GENERATION_STATUS_PENDING | PROCESSING | SUCCESSFUL | FAILED
    }>
    remainingCredits?: number
    captcha?: {                       // Captcha metadata (for debugging/research)
      service: string                 // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
      taskId?: string
      durationMs: number
      attempts: Array<{
        service: string
        taskId?: string
        durationMs: number
        success: boolean
        error?: string
      }>
    }
  }

  error?: string                      // Error message (if failed)
  errorDetails?: string               // Additional error details
  code?: number                       // HTTP status code (if failed)
}
```

**Image Job**

Image generation job structure.

```typescript
{
  jobid: string                       // Unique job identifier
  type: 'image'                       // Job type
  status: 'created' | 'started' | 'completed' | 'failed'
  created: string                     // ISO 8601 creation timestamp
  updated?: string                    // ISO 8601 last update timestamp

  request: {
    email?: string
    prompt: string
    model?: 'imagen-4' | 'nano-banana'
    aspectRatio?: 'landscape' | 'portrait'
    count?: number                    // 1-4
    seed?: number
    reference_1?: string              // mediaGenerationId
    reference_2?: string              // mediaGenerationId
    reference_3?: string              // mediaGenerationId
    replyUrl?: string                 // Webhook URL for callbacks
    replyRef?: string                 // Custom reference for callbacks
  }

  response?: {
    media: Array<{
      name: string
      image: {
        generatedImage: {
          seed: number
          mediaGenerationId: string
          fifeUrl: string             // Signed image URL (valid ~24h)
          prompt: string
        }
      }
    }>
    captcha?: {                       // Captcha metadata (for debugging/research)
      service: string                 // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
      taskId?: string
      durationMs: number
      attempts: Array<{
        service: string
        taskId?: string
        durationMs: number
        success: boolean
        error?: string
      }>
    }
  }

  error?: string                      // Error message (if failed)
  errorDetails?: string               // Additional error details
  code?: number                       // HTTP status code (if failed)
}
```

### Examples

**Curl**
```bash
# Get job status
curl "https://api.useapi.net/v1/google-flow/jobs/j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow" \
  -H "Authorization: Bearer {API token}"

# Poll for completion (check every 5 seconds)
while true; do
  STATUS=$(curl -s "https://api.useapi.net/v1/google-flow/jobs/j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow" \
    -H "Authorization: Bearer {API token}" | jq -r '.status')

  echo "Status: $STATUS"

  if [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]]; then
    break
  fi

  sleep 5
done
```

**JavaScript**
```javascript
const apiToken = 'your-api-token'
const jobId = 'j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow'

// Get job status
async function getJobStatus(jobId) {
  const response = await fetch(`https://api.useapi.net/v1/google-flow/jobs/${jobId}`, {
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  })

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`)
  }

  return await response.json()
}

// Poll until completion
async function waitForCompletion(jobId, intervalMs = 5000) {
  while (true) {
    const job = await getJobStatus(jobId)
    console.log(`Status: ${job.status}`)

    if (job.status === 'completed') {
      console.log('Job completed!', job.response)
      return job
    }

    if (job.status === 'failed') {
      console.error('Job failed:', job.error)
      throw new Error(job.error)
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs))
  }
}

// Usage
const job = await waitForCompletion(jobId)
```

**Python**
```python
import requests
import time

api_token = 'your-api-token'
job_id = 'j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow'

# Get job status
def get_job_status(job_id: str) -> dict:
    response = requests.get(
        f'https://api.useapi.net/v1/google-flow/jobs/{job_id}',
        headers={'Authorization': f'Bearer {api_token}'}
    )
    response.raise_for_status()
    return response.json()

# Poll until completion
def wait_for_completion(job_id: str, interval_sec: int = 5) -> dict:
    while True:
        job = get_job_status(job_id)
        print(f"Status: {job['status']}")

        if job['status'] == 'completed':
            print("Job completed!", job['response'])
            return job

        if job['status'] == 'failed':
            raise Exception(f"Job failed: {job.get('error')}")

        time.sleep(interval_sec)

# Usage
job = wait_for_completion(job_id)

# Access video URLs (for video jobs)
if job['type'] == 'video':
    for op in job['response']['operations']:
        if 'video' in op and 'fifeUrl' in op['video']:
            print(f"Video URL: {op['video']['fifeUrl']}")

# Access image URLs (for image jobs)
if job['type'] == 'image':
    for media in job['response']['media']:
        if 'image' in media and 'generatedImage' in media['image']:
            print(f"Image URL: {media['image']['generatedImage']['fifeUrl']}")
```

### Try It

<script>
  function displayGoogleFlowJobMedia(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (response.type === 'video' && response.response?.operations) {
      const videos = [];
      response.response.operations.forEach((op, index) => {
        if (op.operation?.metadata?.video) {
          const video = op.operation.metadata.video;
          videos.push({
            videoUrl: video.fifeUrl,
            thumbUrl: video.servingBaseUri,
            seed: video.seed,
            label: `Video ${videos.length + 1}${video.seed ? ` (seed: ${video.seed})` : ''}`
          });
        }
      });

      if (videos.length > 0) {
        const linksHTML = videos.map(vid =>
          `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`
        ).join(' ');

        mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Videos:</strong> ${linksHTML}</div>`;
        mediaContainer.style.display = 'block';
        return;
      }
    }

    if (response.type === 'image' && response.response?.media) {
      const images = [];
      response.response.media.forEach((item, index) => {
        if (item.image?.generatedImage) {
          const img = item.image.generatedImage;
          images.push({
            url: img.fifeUrl,
            seed: img.seed,
            label: `Image ${index + 1}${img.seed ? ` (seed: ${img.seed})` : ''}`
          });
        }
      });

      if (images.length > 0) {
        const linksHTML = images.map(img =>
          `<a href="${img.url}" target="_blank" rel="noopener noreferrer" class="media-link image">${img.label}</a>`
        ).join(' ');

        mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Images:</strong> ${linksHTML}</div>`;
        mediaContainer.style.display = 'block';
        return;
      }
    }

    mediaContainer.style.display = 'none';
  }

  async function apiExecuteGetGoogleFlowJobsJobId() {
    const tokenElement = document.getElementById('input-token');
    const jobIdElement = document.getElementById('input-jobid');
    const elementId = 'input';

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute(
      `https://api.useapi.net/v1/google-flow/jobs/${jobIdElement.value}`,
      elementId,
      data
    );

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayGoogleFlowJobMedia(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for media display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobid"><span>jobId<small> (required)</small></span>
        <input id="input-jobid" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowJobsJobId()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs ===
Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs
## Get Load Balancing Statistics
<small>November 17, 2025 (November 19, 2025)</small>

---

Get load balancing statistics across all configured Google Flow accounts. This endpoint provides real-time visibility into job distribution, account health, and performance metrics for both image and video generation.

To retrieve a specific job, use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid).
> **https://api.useapi.net/v1/google-flow/jobs/?options=`options`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Query Parameters

- `options` is optional, controls the level of detail in the response (default: `summary`).  
  Supported values:
  - `summary`: Returns aggregated stats per account (executing, completed, failed, rate limited counts)
  - `executing`: Adds details of currently executing jobs with elapsed time
  - `history`: Includes top 10 most recent completed jobs from the last 15 minutes

### Load Balancing Algorithm

When you have multiple Google Flow accounts configured and don't specify an `email` parameter in [POST /images](/docs/api-google-flow-v1/post-google-flow-images) or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), the API automatically selects the best account in two steps: a **quarantine pre-filter**, then a **scoring algorithm** over the survivors.

#### Step 1 — Quarantine pre-filter

Accounts that recently hit a known recoverable Google quota or throttle are **excluded from scoring entirely** until their quarantine expires. This avoids retrying an account that we already know cannot succeed, and pushes load to the remaining healthy accounts.

Quarantines are recorded automatically when a generation request returns `429` with one of these reasons:

| Reason | Scope | Cleared at |
|--------|-------|-----------|
| `PUBLIC_ERROR_USER_QUOTA_REACHED` | All models on that account | Next UTC midnight |
| `PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED` | Only the model that failed (other models on the same account remain eligible) | Next UTC midnight |
| `PUBLIC_ERROR_USER_REQUESTS_THROTTLED` | All models on that account | ~30 minutes after first hit |

Quarantine is **idempotent**: repeated 429s for the same `(account, reason, model)` tuple preserve the original `firstSeen` timestamp; only the entry's TTL is refreshed if needed.

If **every** account is quarantined for the requested model, the API returns `429` with `error: "no_eligible_account"` and a `Retry-After` header indicating the earliest cooldown. See the 429 response details on the image/video endpoints: [POST /images](/docs/api-google-flow-v1/post-google-flow-images#post-v1googleflow-images-429) / [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#post-v1googleflow-videos-429).

**Explicit `email` bypasses the filter.** If you specify an `email` parameter, the load balancer is skipped entirely — your request goes to that account even if it's quarantined.

#### Step 2 — Scoring

Among the accounts that survive Step 1, the API picks the one with the lowest score:

**Formula:** `score = executing + (failed × 10) + (rateLimited × 20)`

**Lower scores are better.** The account with the lowest score receives the next job.

**Components:**
- `executing`: Number of jobs currently running on this account
  Weight: **1×** (each executing job adds 1 point)
  Purpose: Distribute load evenly across accounts

- `failed`: Number of failed jobs (non-429 4xx/5xx responses) in last 15 minutes
  Weight: **10×** (each failure adds 10 points)
  Purpose: Heavily penalize unreliable accounts

- `rateLimited`: Number of 429 rate limit responses in last 15 minutes
  Weight: **20×** (each rate limit adds 20 points)
  Purpose: Most heavily penalize rate-limited accounts to avoid hitting limits

**Example scores:**
- Idle account: `0 executing + 0 failed + 0 rateLimited = 0` (best)
- 2 jobs running: `2 executing + 0 failed + 0 rateLimited = 2`
- 1 recent failure: `0 executing + 1 failed + 0 rateLimited = 10`
- 1 rate limit hit: `0 executing + 0 failed + 1 rateLimited = 20`
- Rate limited account: `0 executing + 0 failed + 2 rateLimited = 40` (worst)

**Randomization:** When multiple accounts have the same score, one is selected randomly.

**Stats expiration:** Job statistics older than 15 minutes are automatically removed from load balancing calculations.

### Responses

**200**
**200 OK**

Returns load balancing statistics categorized by job type.

**With `options=summary` (default):**

```json
{
  "emails": [
    "jo***@gmail.com",
    "an***@gmail.com"
  ],
  "videos": {
    "summary": {
      "jo***@gmail.com": {
        "executing": 2,
        "completed": 15,
        "failed": 0,
        "rateLimited": 0,
        "avgResponseTime": 125340.50,
        "score": 2
      },
      "an***@gmail.com": {
        "executing": 0,
        "completed": 8,
        "failed": 1,
        "rateLimited": 0,
        "avgResponseTime": 98234.75,
        "score": 10
      }
    }
  },
  "images": {
    "summary": {
      "jo***@gmail.com": {
        "executing": 1,
        "completed": 42,
        "failed": 0,
        "rateLimited": 0,
        "avgResponseTime": 12456.30,
        "score": 1
      },
      "an***@gmail.com": {
        "executing": 0,
        "completed": 38,
        "failed": 0,
        "rateLimited": 1,
        "avgResponseTime": 15234.80,
        "score": 20
      }
    }
  },
  "combined": {
    "summary": {
      "jo***@gmail.com": {
        "executing": 3,
        "completed": 57,
        "failed": 0,
        "rateLimited": 0,
        "avgResponseTime": 32145.60,
        "score": 3
      },
      "an***@gmail.com": {
        "executing": 0,
        "completed": 46,
        "failed": 1,
        "rateLimited": 1,
        "avgResponseTime": 42367.25,
        "score": 30
      }
    }
  }
}
```

**With `options=executing`:**

Adds `executing` object with currently running jobs and their elapsed time in `MM:SS` format:

```json
{
  "emails": [
    "jo***@gmail.com",
    "an***@gmail.com"
  ],
  "videos": {
    "summary": { "..." },
    "executing": {
      "j1731...redacted...v-u12345-email:jo***@gmail.com-bot:google-flow": {
        "email": "jo***@gmail.com",
        "timestamp": 1731859234567,
        "elapsed": "1:23"
      },
      "j1731...redacted...v-u12345-email:jo***@gmail.com-bot:google-flow-http:200": {
        "email": "jo***@gmail.com",
        "timestamp": 1731859123456,
        "elapsed": "3:45"
      }
    }
  },
  "images": {
    "summary": { "..." },
    "executing": {
      "j1731...redacted...i-u12345-email:jo***@gmail.com-bot:google-flow": {
        "email": "jo***@gmail.com",
        "timestamp": 1731859345678,
        "elapsed": "0:15"
      }
    }
  },
  "combined": {
    "summary": { "..." }
  }
}
```

**With `options=history`:**

Adds both `executing` and `history` objects with top 10 most recent completed jobs from last 15 minutes:

```json
{
  "emails": [
    "jo***@gmail.com",
    "an***@gmail.com"
  ],
  "videos": {
    "summary": { "..." },
    "executing": { "..." },
    "history": {
      "j1731...redacted...v-u12345-email:jo***@gmail.com-bot:google-flow": {
        "email": "jo***@gmail.com",
        "timestamp": 1731858123456,
        "httpStatus": 200,
        "responseTime": 125340
      },
      "j1731...redacted...v-u12345-email:an***@gmail.com-bot:google-flow": {
        "email": "an***@gmail.com",
        "timestamp": 1731858234567,
        "httpStatus": 500,
        "responseTime": 98234
      }
    }
  },
  "images": {
    "summary": { "..." },
    "executing": { "..." },
    "history": { "..." }
  },
  "combined": {
    "summary": { "..." }
  }
}
```

**400**
**400 Bad Request**

Invalid `options` parameter value.

```json
{
  "error": "Invalid options parameter. Use: summary, executing, or history"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model

```typescript
{
  emails: string[]                    // List of all configured healthy account emails
  videos: {
    summary: {
      [email: string]: {
        executing: number             // Currently running jobs
        completed: number             // Successfully completed (2xx) in last 15min
        failed: number                // Failed (4xx/5xx except 429) in last 15min
        rateLimited: number           // Rate limited (429) in last 15min
        avgResponseTime: number       // Average response time in milliseconds
        score: number                 // Load balancing score (lower is better)
      }
    }
    executing?: {                     // Only with options=executing or history
      [jobId: string]: {
        email: string                 // Account email
        timestamp: number             // Unix timestamp (milliseconds)
        elapsed: string               // Elapsed time in MM:SS format
      }
    }
    history?: {                       // Only with options=history
      [jobId: string]: {
        email: string                 // Account email
        timestamp: number             // Unix timestamp (milliseconds)
        httpStatus: number            // HTTP status code (200, 429, 500, etc.)
        responseTime: number          // Response time in milliseconds
      }
    }
  }
  images: {
    summary: {
      [email: string]: {
        executing: number             // Currently running jobs
        completed: number             // Successfully completed (2xx) in last 15min
        failed: number                // Failed (4xx/5xx except 429) in last 15min
        rateLimited: number           // Rate limited (429) in last 15min
        avgResponseTime: number       // Average response time in milliseconds
        score: number                 // Load balancing score (lower is better)
      }
    }
    executing?: {                     // Only with options=executing or history
      [jobId: string]: {
        email: string                 // Account email
        timestamp: number             // Unix timestamp (milliseconds)
        elapsed: string               // Elapsed time in MM:SS format
      }
    }
    history?: {                       // Only with options=history
      [jobId: string]: {
        email: string                 // Account email
        timestamp: number             // Unix timestamp (milliseconds)
        httpStatus: number            // HTTP status code (200, 429, 500, etc.)
        responseTime: number          // Response time in milliseconds
      }
    }
  }
  combined: {
    summary: {
      [email: string]: {
        executing: number             // Currently running jobs
        completed: number             // Successfully completed (2xx) in last 15min
        failed: number                // Failed (4xx/5xx except 429) in last 15min
        rateLimited: number           // Rate limited (429) in last 15min
        avgResponseTime: number       // Average response time in milliseconds
        score: number                 // Load balancing score (lower is better)
      }
    }
  }
}
```

### Examples

**Curl**
```bash
# Get summary stats (default)
curl "https://api.useapi.net/v1/google-flow/jobs" \
  -H "Authorization: Bearer {API token}"

# Get executing jobs with elapsed time
curl "https://api.useapi.net/v1/google-flow/jobs/?options=executing" \
  -H "Authorization: Bearer {API token}"

# Get full history (last 15 minutes)
curl "https://api.useapi.net/v1/google-flow/jobs/?options=history" \
  -H "Authorization: Bearer {API token}"
```

**JavaScript**
```javascript
const apiToken = 'your-api-token'

// Get summary stats (default)
const response = await fetch('https://api.useapi.net/v1/google-flow/jobs', {
  headers: {
    'Authorization': `Bearer ${apiToken}`
  }
})

const stats = await response.json()

// Check which account has lowest score for images
const imagesSummary = stats.images.summary
const bestAccount = Object.entries(imagesSummary)
  .sort(([, a], [, b]) => a.score - b.score)[0]

console.log('Best account for images:', bestAccount[0], 'score:', bestAccount[1].score)

// Get executing jobs
const execResponse = await fetch('https://api.useapi.net/v1/google-flow/jobs/?options=executing', {
  headers: {
    'Authorization': `Bearer ${apiToken}`
  }
})

const execStats = await execResponse.json()
console.log('Currently executing videos:', Object.keys(execStats.videos.executing || {}).length)
```

**Python**
```python
import requests

api_token = 'your-api-token'
headers = {'Authorization': f'Bearer {api_token}'}

# Get summary stats (default)
response = requests.get(
    'https://api.useapi.net/v1/google-flow/jobs',
    headers=headers
)

stats = response.json()

# Check which account has lowest score for videos
videos_summary = stats['videos']['summary']
best_account = min(videos_summary.items(), key=lambda x: x[1]['score'])

print(f"Best account for videos: {best_account[0]}, score: {best_account[1]['score']}")

# Get full history
history_response = requests.get(
    'https://api.useapi.net/v1/google-flow/jobs/?options=history',
    headers=headers
)

history_stats = history_response.json()
print(f"Image job history entries: {len(history_stats['images'].get('history', {}))}")
```

### Try It

<script>
  async function apiExecuteGetGoogleFlowJobs() {
    const tokenElement = document.getElementById('input-token');
    const optionsElement = document.getElementById('input-options');

    const url = new URL('https://api.useapi.net/v1/google-flow/jobs/');
    if (optionsElement.value) {
      url.searchParams.append('options', optionsElement.value);
    }

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(url.toString(), 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-options"><span>options<small> (optional)</small></span>
        <select id="input-options" class="input-element">
          <option value="summary">summary (default)</option>
          <option value="executing">executing</option>
          <option value="history">history</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowJobs()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1 ===
Document URL: https://useapi.net/docs/api-google-flow-v1

# <img style="height:1em;vertical-align: middle;" src="/assets/images/google-flow.svg"> Google Flow API v1
<small>November 17, 2025 (May 11, 2026)</small>

This is the [experimental](/docs/legal) API for [Google Flow](https://labs.google/fx/tools/flow) by [Google Labs](https://labs.google).

[Google Flow](https://labs.google/fx/tools/flow) creates cinematic AI clips with [Veo](https://aistudio.google.com/models/veo-3), images with [Imagen 4](https://deepmind.google/technologies/imagen-3/), [Nano Banana / Gemini 2.5 Flash Image](https://deepmind.google/technologies/gemini/flash/), [Nano Banana 2 / Gemini 2.5 Pro Image](https://deepmind.google/technologies/gemini/), and [Nano Banana Pro / Gemini 3 Pro Image](https://deepmind.google/models/gemini-image/pro/).

**Image generation:** Works with any [Google AI](https://one.google.com/ai) subscription or **free** account.

**Video generation:** Requires [Google AI Pro](https://one.google.com/ai) ($20/month) or [Ultra](https://one.google.com/ai) ($125/month):
- `Veo 3.1 Lite` — 2.5¢ per video (5 credits)
- `Veo 3.1 Fast` — 5¢ per video (10 credits)
- `Veo 3.1 Quality` — 50¢ per video (100 credits)
- `Veo 3.1 Lite Lower Priority` — free, Ultra only (lower priority)
- Voice narration — 30 AI voice presets for spoken dialogue (works with R2V mode)
- Output duration — `4`, `6`, or `8` seconds (default `8`); `4` and `6` require Ultra and apply only to T2V/I2V/I2V-FL modes

Official Google AI Pro and Google AI Ultra [credits table](https://support.google.com/googleone/answer/16287445).

You can configure up to 50 Google Flow accounts per single [useapi.net subscription](/docs/subscription).

**Captcha:** Image and video generation ([POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend)) requires reCAPTCHA solving. [POST /videos/gif](/docs/api-google-flow-v1/post-google-flow-videos-gif) and [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) do not require captcha.

- **Users receive 100 free captcha credits** (powered by [CapSolver](https://www.capsolver.com/)) when adding their first Google Flow account
- After free credits are exhausted, configure provider API keys via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)
- Cost: ~$0.80-$3.00 per 1,000 solves depending on provider
- Compare provider success rates with [GET /accounts/captcha-stats?anonymized=true](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats)
- See [Setup Google Flow - Captcha Providers](/docs/start-here/setup-google-flow#configure-captcha-providers) for details

⚙️ [Setup Google Flow](/docs/start-here/setup-google-flow)

📦 [Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(May 4, 2026)</small>  
🤖 [LLM-friendly API spec](https://useapi.net/assets/aibot/api-google-flow-v1.txt) <small>Feed this to your LLM to build integrations</small>  

Examples:
* [Veo 3.1 Lite & Voice Narration](/blog/260403)
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [Video Extend and Concatenate](/blog/260129)
* [Video Upscale and GIF](/blog/260120)
* [Nano Banana Pro with 5 references](/blog/251201)
* [Nano Banana Pro](/blog/251120)
* [Imagen 4, Nano Banana and Veo 3.1 Fast](/blog/251117)
  
Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/GoogleFlowAPI/"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/GoogleFlowAPI</a>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers
## Configure Captcha Providers
<small>December 23, 2025 (February 18, 2026)</small>

---

Configure captcha provider API keys for image and video generation. Google Flow requires reCAPTCHA v3 Enterprise tokens for API calls - these third-party services solve the captcha automatically.

**Supported Providers:**

| Provider | Cost per 1K | Avg Solve Time | Reports Back | Website |
|----------|-------------|----------------|:------------:|---------|
| **CapSolver** | ~$3.00 | ~8-12s | [Yes](https://docs.capsolver.com/en/api/) | [capsolver.com](https://www.capsolver.com/) — use promo code `useapi` for 8% discount |
| **AntiCaptcha** | ~$2.00 | ~8-12s | [Yes](https://anti-captcha.com/apidoc/methods/reportCorrectRecaptcha) | [anti-captcha.com](https://anti-captcha.com/) |
| **YesCaptcha** | varies | ~8-12s | No | [yescaptcha.com](https://yescaptcha.com/) |
| **SolveCaptcha** | ~$0.80 | ~30-60s ⚠️ | [Yes](https://solvecaptcha.com/captcha-solver-api) | [solvecaptcha.com](https://solvecaptcha.com/) |
| **2Captcha** | ~$2.99 | ~30-60s ⚠️ | [Yes](https://2captcha.com/api-docs/report-correct) | [2captcha.com](https://2captcha.com/) |
| **EzCaptcha** | ~$2.50 | ~8-12s | No | [ez-captcha.com](https://www.ez-captcha.com/) — currently not recommended due to low solve rate |

⚠️ SolveCaptcha and 2Captcha typically take 30-60 seconds per solve compared to ~8-12 seconds for other providers. They work well as low-cost fallbacks but may increase overall request latency when used as primary providers.

**Reports Back** — providers that support solve result reporting receive feedback (correct/incorrect) after each captcha use. This helps improve token quality over time as providers learn from the results.

Use [GET /accounts/captcha-stats?anonymized=true](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) to compare success rates across providers. Configure multiple providers for redundancy - the API will automatically retry with different providers if one fails or returns a rejected token.

### Captcha Parameters
These parameters are available on all endpoints that require captcha: [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend).

- `captchaToken` — a user-provided reCAPTCHA v3 Enterprise token. When provided, the API uses this token directly instead of solving captcha through a provider. Single attempt, no retry. Must be a valid token string (minimum 20 characters).
- `captchaRetry` — number of captcha retry attempts (1-10, default: 3). Cycles through configured providers in priority order (see below). Each attempt uses the next provider in the sequence, wrapping around if needed.
- `captchaOrder` — explicit captcha provider sequence as comma-separated string (e.g., `"AntiCaptcha,AntiCaptcha,CapSolver"`). Maximum 10 entries. Each provider must have an API key configured. Overrides the default provider order.

**Note:** `captchaToken`, `captchaRetry`, and `captchaOrder` are mutually exclusive - only one can be specified per request.

**Default provider order:** CapSolver → AntiCaptcha → YesCaptcha → CapMonster → SolveCaptcha → 2Captcha → EzCaptcha. The API prioritizes faster providers first. If CapSolver is configured, it is always used first. Remaining providers follow the order listed above.
> **https://api.useapi.net/v1/google-flow/accounts/captcha-providers**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "CapSolver": "<your CapSolver API key>",
  "AntiCaptcha": "<your AntiCaptcha API key>",
  "YesCaptcha": "<your YesCaptcha API key>",
  "SolveCaptcha": "<your SolveCaptcha API key>",
  "2Captcha": "<your 2Captcha API key>",
  "EzCaptcha": "<your EzCaptcha API key>"
}
```

- `CapSolver` is optional. API key from [capsolver.com](https://www.capsolver.com/).
- `AntiCaptcha` is optional. API key from [anti-captcha.com](https://anti-captcha.com/).
- `YesCaptcha` is optional. API key from [yescaptcha.com](https://yescaptcha.com/).
- `SolveCaptcha` is optional. API key from [solvecaptcha.com](https://solvecaptcha.com/).
- `2Captcha` is optional. API key from [2captcha.com](https://2captcha.com/).
- `EzCaptcha` is optional. API key from [ez-captcha.com](https://www.ez-captcha.com/).

**Notes:**
- All fields are optional - only include providers you want to configure
- Set a field to empty string `""` to remove that provider
- Users receive **100 free captcha credits** (powered by [CapSolver](https://www.capsolver.com/)) when adding their first Google Flow account. These credits are used automatically when no provider API keys are configured.
- Once free credits are exhausted, at least one provider must be configured to use [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos)

### Responses

**200**
**200 OK**

Captcha providers configured successfully. Returns masked keys for all configured providers.

**With providers configured:**
```json
{
  "CapSolver": "abc...***...xyz",
  "AntiCaptcha": "def...***...uvw"
}
```

**All providers removed (shows free credits if available):**
```json
{
  "freeCaptchaCredits": 100
}
```

**400**
**400 Bad Request**

Invalid provider name specified.

```json
{
  "error": "Invalid captcha provider(s): InvalidProvider. Valid providers: CapSolver, AntiCaptcha, YesCaptcha, CapMonster, SolveCaptcha, 2Captcha, EzCaptcha"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model

```typescript
{ // TypeScript, all fields are optional
  CapSolver?: string          // Masked API key or omitted if not configured
  AntiCaptcha?: string        // Masked API key or omitted if not configured
  YesCaptcha?: string         // Masked API key or omitted if not configured
  CapMonster?: string         // Masked API key or omitted if not configured
  SolveCaptcha?: string       // Masked API key or omitted if not configured
  '2Captcha'?: string         // Masked API key or omitted if not configured
  EzCaptcha?: string          // Masked API key or omitted if not configured
  freeCaptchaCredits?: number // Remaining free credits (only shown when no providers configured)
}
```

**Note:** `freeCaptchaCredits` is only included in the response when:
- No captcha providers are configured (all removed), AND
- The user has remaining free credits (> 0)

### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -X POST "https://api.useapi.net/v1/google-flow/accounts/captcha-providers" \
     -d '{
       "AntiCaptcha": "<your AntiCaptcha API key>",
       "CapSolver": "<your CapSolver API key>"
     }'
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers';
const token = 'YOUR_API_TOKEN';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    AntiCaptcha: '<your AntiCaptcha API key>',
    CapSolver: '<your CapSolver API key>'
  })
});

const result = await response.json();
console.log('Captcha providers configured:', result);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers'
token = 'YOUR_API_TOKEN'

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

body = {
    'AntiCaptcha': '<your AntiCaptcha API key>',
    'CapSolver': '<your CapSolver API key>'
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response.status_code, response.json())
```

### Try It

<script>
  async function apiTestCaptchaProvidersPost() {
      const body = {};

      const antiCaptchaClear = document.getElementById('post-captcha-providers-AntiCaptcha-clear')?.checked;
      const ezCaptchaClear = document.getElementById('post-captcha-providers-EzCaptcha-clear')?.checked;
      const capSolverClear = document.getElementById('post-captcha-providers-CapSolver-clear')?.checked;
      const yesCaptchaClear = document.getElementById('post-captcha-providers-YesCaptcha-clear')?.checked;
      const solveCaptchaClear = document.getElementById('post-captcha-providers-SolveCaptcha-clear')?.checked;
      const twoCaptchaClear = document.getElementById('post-captcha-providers-2Captcha-clear')?.checked;
      const antiCaptcha = document.getElementById('post-captcha-providers-AntiCaptcha')?.value;
      const ezCaptcha = document.getElementById('post-captcha-providers-EzCaptcha')?.value;
      const capSolver = document.getElementById('post-captcha-providers-CapSolver')?.value;
      const yesCaptcha = document.getElementById('post-captcha-providers-YesCaptcha')?.value;
      const solveCaptcha = document.getElementById('post-captcha-providers-SolveCaptcha')?.value;
      const twoCaptcha = document.getElementById('post-captcha-providers-2Captcha')?.value;
      if (antiCaptchaClear) body.AntiCaptcha = '';
      else if (antiCaptcha !== undefined && antiCaptcha !== '') body.AntiCaptcha = antiCaptcha;

      if (ezCaptchaClear) body.EzCaptcha = '';
      else if (ezCaptcha !== undefined && ezCaptcha !== '') body.EzCaptcha = ezCaptcha;

      if (capSolverClear) body.CapSolver = '';
      else if (capSolver !== undefined && capSolver !== '') body.CapSolver = capSolver;

      if (yesCaptchaClear) body.YesCaptcha = '';
      else if (yesCaptcha !== undefined && yesCaptcha !== '') body.YesCaptcha = yesCaptcha;

      if (solveCaptchaClear) body.SolveCaptcha = '';
      else if (solveCaptcha !== undefined && solveCaptcha !== '') body.SolveCaptcha = solveCaptcha;

      if (twoCaptchaClear) body['2Captcha'] = '';
      else if (twoCaptcha !== undefined && twoCaptcha !== '') body['2Captcha'] = twoCaptcha;

      const data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-captcha-providers-api_token').value}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(body)
      };

      await apiExecute('https://api.useapi.net/v1/google-flow/accounts/captcha-providers', 'post-captcha-providers', data);
  }
</script>

<form id="post-captcha-providers" onsubmit="return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-captcha-providers-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-captcha-providers-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-AntiCaptcha"><span>AntiCaptcha<small> (optional) <input id="post-captcha-providers-AntiCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-AntiCaptcha').value=''"> Clear</small></span>
        <input id="post-captcha-providers-AntiCaptcha" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-EzCaptcha"><span>EzCaptcha<small> (optional) <input id="post-captcha-providers-EzCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-EzCaptcha').value=''"> Clear</small></span>
        <input id="post-captcha-providers-EzCaptcha" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-CapSolver"><span>CapSolver<small> (optional) <input id="post-captcha-providers-CapSolver-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-CapSolver').value=''"> Clear</small></span>
        <input id="post-captcha-providers-CapSolver" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-YesCaptcha"><span>YesCaptcha<small> (optional) <input id="post-captcha-providers-YesCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-YesCaptcha').value=''"> Clear</small></span>
        <input id="post-captcha-providers-YesCaptcha" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-SolveCaptcha"><span>SolveCaptcha<small> (optional) <input id="post-captcha-providers-SolveCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-SolveCaptcha').value=''"> Clear</small></span>
        <input id="post-captcha-providers-SolveCaptcha" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
      <label for="post-captcha-providers-2Captcha"><span>2Captcha<small> (optional) <input id="post-captcha-providers-2Captcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-2Captcha').value=''"> Clear</small></span>
        <input id="post-captcha-providers-2Captcha" type="text" class="input-element" oninput="this.size = this.value.length">
      </label>
    </div>
    <button id="post-captcha-providers-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestCaptchaProvidersPost()">Go</button>
  </div>
</form>

<div id="post-captcha-providers-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts
## Configure Google Flow Account
<small>November 17, 2025</small>

---

Configure your Google Flow account for API access using cookies from your authenticated Google account.

You can configure up to 50 Google Flow accounts per single [useapi.net subscription](/docs/subscription).
> **https://api.useapi.net/v1/google-flow/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "cookies": "Name\tValue\tDomain\tPath\tExpires\t..."
}
```

- `cookies` is **required**. Cookies copied from Chrome DevTools in table format. See [Setup Google Flow](/docs/start-here/setup-google-flow) for detailed instructions on how to obtain these cookies.

### Responses

**201**
**201 Created**

New account configuration created successfully.

```json
{
  "accountCookies": [
    {
      "name": "HSID",
      "value": "AYQ...(redacted)",
      "domain": ".google.com",
      "path": "/",
      "expires": "2027-11-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "sessionCookies": [
    {
      "name": "__Host-GAPS",
      "value": "1:eJy...(redacted)",
      "domain": "labs.google",
      "path": "/",
      "expires": "2025-12-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "sessionData": {
    "user": {
      "name": "John Doe",
      "email": "jo***@gmail.com",
      "image": "https://lh3.googleusercontent.com/a/..."
    },
    "expires": "2025-11-11T12:00:00.000Z",
    "access_token": "ya29.a0A...(redacted)"
  },
  "created": "2025-11-10T12:00:00.000Z",
  "project": {
    "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d",
    "projectTitle": "Nov 11 - 02:56"
  },
  "nextRefresh": {
    "messageId": "msg-abc123",
    "scheduledFor": "2025-11-11T11:00:00.000Z"
  }
}
```

**200**
**200 OK**

Existing account configuration updated successfully.

```json
{
  "accountCookies": [
    {
      "name": "HSID",
      "value": "AYQ...(redacted)",
      "domain": ".google.com",
      "path": "/",
      "expires": "2027-11-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "sessionCookies": [
    {
      "name": "__Host-GAPS",
      "value": "1:eJy...(redacted)",
      "domain": "labs.google",
      "path": "/",
      "expires": "2025-12-10T12:00:00.000Z",
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "sessionData": {
    "user": {
      "name": "John Doe",
      "email": "jo***@gmail.com",
      "image": "https://lh3.googleusercontent.com/a/..."
    },
    "expires": "2025-11-11T12:00:00.000Z",
    "access_token": "ya29.a0A...(redacted)"
  },
  "created": "2025-11-10T12:00:00.000Z",
  "project": {
    "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d",
    "projectTitle": "Nov 11 - 02:56"
  },
  "nextRefresh": {
    "messageId": "msg-abc123",
    "scheduledFor": "2025-11-11T11:00:00.000Z"
  }
}
```

**400**
**400 Bad Request**

Validation error (missing/invalid parameters or cookies).

```json
{
  "error": "Failed to validate cookies: 401 Unauthorized"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

### Model

- `created` - ISO 8601 timestamp when the account was first configured
- `accountCookies` - Google account cookies 
- `sessionCookies` - Session cookies for Google Flow
- `sessionData` - User session information with access token
- `project` - Auto-created Google Flow project for this session
- `nextRefresh` - Scheduled refresh details (refreshes automatically 1 hour before expiry)

```typescript
{ // TypeScript, all fields are optional
  created: string              // ISO 8601 timestamp
  accountCookies: Array<{
    name: string
    value: string              
    domain: string
    path: string
    expires: string | number
    httpOnly: boolean
    secure: boolean
    sameSite: 'Lax' | 'Strict' | 'None'
  }>
  sessionCookies: Array<{     
    name: string
    value: string             
    domain: string
    path: string
    expires: string | number
    httpOnly: boolean
    secure: boolean
    sameSite: 'Lax' | 'Strict' | 'None'
  }>
  sessionData: {
    user: {
      name: string
      email: string
      image: string
    }
    expires: string            // ISO 8601 timestamp
    access_token: string       
  }
  project: {
    projectId: string
    projectTitle: string
  }
  nextRefresh: {
    messageId: string
    scheduledFor: string       // ISO 8601 timestamp
  }
  health?: string              // "OK" | "Error information"
  error?: string               // Error message 
}
```

### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -X POST "https://api.useapi.net/v1/google-flow/accounts" \
     -d '{
       "cookies": "HSID\tAYQ...\t.google.com\t/\t2027-11-10...\nSSID\tAbc...\t.google.com\t/\t2027-11-10..."
     }'
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts';
const token = 'YOUR_API_TOKEN';
const cookies = `HSID\tAYQ...\t.google.com\t/\t2027-11-10...
SSID\tAbc...\t.google.com\t/\t2027-11-10...`;

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cookies: cookies
  })
});

const result = await response.json();
console.log('Account configured:', result);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v1/google-flow/accounts'
token = 'YOUR_API_TOKEN'
cookies = """HSID\tAYQ...\t.google.com\t/\t2027-11-10...
SSID\tAbc...\t.google.com\t/\t2027-11-10..."""

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

body = {
    'cookies': cookies
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response.status_code, response.json())
```

### Try It

See [Setup Google Flow](/docs/start-here/setup-google-flow) page.

<script>
  async function apiTestAccountGoogleFlow() {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-GoogleFlow-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let cookies = document.getElementById(`post-accounts-GoogleFlow-cookies`)?.value;

      data.body = JSON.stringify({
          cookies
      });

      await apiExecute(`https://api.useapi.net/v1/google-flow/accounts`, 'post-accounts-GoogleFlow', data);
  }
</script>

<form id="post-accounts-GoogleFlow" onsubmit="return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-GoogleFlow-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-GoogleFlow-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-GoogleFlow-cookies"><span>cookies</span>
        <textarea id="post-accounts-GoogleFlow-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea>
      </label>
    </div>
    <button id="post-accounts-GoogleFlow-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestAccountGoogleFlow()">Go</button>
  </div>
</form>

<div id="post-accounts-GoogleFlow-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-assets-email ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-assets-email
## Upload Assets
<small>November 17, 2025 (February 27, 2026)</small>

---

Upload assets to Google Flow. Currently supported formats are PNG, JPEG, and WebP with a maximum file size of 20 MB.

| Content-Type | File Extension |
| ------------ | -------------- |
| image/png    | png            |
| image/jpeg   | jpeg           |
| image/webp   | webp           |

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/google-flow/assets/`email`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table above
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.
- `Content-Type` is **required**, see table above.

### Path Parameters

- `email` is optional. The email address of the Google Flow account to use (URL-encoded if necessary).

  When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **image generation** job statistics to select the healthiest account.

  **Note:** The endpoint can be called as either `POST /assets` (no email) or `POST /assets/:email` (explicit email).

### Request Body

Binary image content (raw bytes).

### Responses

**200**
**200 OK**

Image uploaded successfully. Returns media details, the media generation ID with reference ID, image dimensions, and the account email used.

```json
{
  "media": {
    "name": "ff9aa5cc-...redacted...",
    "projectId": "5c37e988-...redacted...",
    "workflowId": "69603881-...redacted...",
    "workflowStepId": "CAE",
    "mediaMetadata": {
      "createTime": "2026-02-27T16:34:25.128454Z",
      "requestData": {
        "clientPlatform": "CLIENT_PLATFORM_WEB"
      },
      "visibility": "PRIVATE"
    },
    "image": {
      "userUploadedImage": {
        "aspectRatio": "IMAGE_ASPECT_RATIO_UNSPECIFIED"
      },
      "dimensions": {
        "width": 1024,
        "height": 1024
      }
    }
  },
  "workflow": {
    "name": "69603881-...redacted...",
    "metadata": {
      "displayName": "upload.webp",
      "createTime": "2026-02-27T16:34:25.128454Z",
      "primaryMediaId": "ff9aa5cc-...redacted..."
    },
    "projectId": "5c37e988-...redacted..."
  },
  "mediaGenerationId": {
    "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-...redacted..."
  },
  "width": 1024,
  "height": 1024,
  "email": "jo***@gmail.com"
}
```

- `media` - Full media object from Google Flow API with upload details and dimensions
- `media.image.dimensions` - Image dimensions as reported by Google (`width` and `height`)
- `workflow` - Workflow metadata including display name and project ID
- `mediaGenerationId.mediaGenerationId` - Reference ID for use in subsequent API calls (format: `user:{userid}-email:{hex_encoded_email}-image:{internal_media_id}`)
- `width` - Image width in pixels
- `height` - Image height in pixels
- `email` - Account email that was used for the upload (useful when email was omitted and auto-selected via load balancing)

**400**
**400 Bad Request**

Invalid request (empty content, unsupported content type, file too large, or content policy violation).

**General error:**
```json
{
  "error": "File size (25165824) is over 20971520 bytes"
}
```

**Content policy error:**
```json
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_TRUMP_FACE_DETECTED"
      }
    ]
  }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**429**
**429 Too Many Requests**

Rate limit or quota exhausted (concurrency limit or account quota reached). Wait 5-10 seconds and retry. If this persists, you may need to cool this account off for a few hours before trying again.

```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_REQUESTS_THROTTLED"
      }
    ]
  }
}
```

**596**
**596 Session Error**

Google session refresh failed. The account needs to be reconfigured. Delete the account using [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by strictly following the procedure in [Setup Google Flow](/docs/start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session: 500 Internal Server Error"
}
```

### Model
```typescript
{
  media: {                              // Full media object from Google Flow API
    name: string                        // Media UUID
    projectId: string
    workflowId: string
    workflowStepId: string
    mediaMetadata?: {
      createTime?: string               // ISO 8601 timestamp
      requestData?: object
      visibility?: string               // "PRIVATE"
    }
    image?: {
      userUploadedImage?: {
        aspectRatio: string             // "IMAGE_ASPECT_RATIO_UNSPECIFIED" | "LANDSCAPE" | "PORTRAIT"
      }
      dimensions?: {
        width: number
        height: number
      }
    }
  }
  workflow?: {                          // Workflow metadata
    name: string                        // Workflow UUID
    metadata?: {
      displayName?: string              // Original filename
      createTime?: string
      primaryMediaId?: string           // Same as media.name
    }
    projectId?: string
  }
  mediaGenerationId: {
    mediaGenerationId: string           // Reference ID: user:{userid}-email:{hex_encoded_email}-image:{internal_media_id}
  }
  width: number                         // Image width in pixels
  height: number                        // Image height in pixels
  email: string                         // Account email used for upload
  error?: string | {                    // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details: Array<{
      '@type': string
      reason: string
    }>
  }
}
```

### Examples

**Curl**
``` bash
# Option 1: Without email (auto-selection/load balancing)
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: image/jpeg" \
     --data-binary @/path/to/your/image.jpeg \
     "https://api.useapi.net/v1/google-flow/assets"

# Option 2: With specific email
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: image/jpeg" \
     --data-binary @/path/to/your/image.jpeg \
     "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// Option 1: Without email (auto-selection/load balancing)
const apiUrl = 'https://api.useapi.net/v1/google-flow/assets';

// Option 2: With specific email
// const email = 'john@gmail.com';
// const apiUrl = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(email)}`;

// Load image - Example 1: Fetch from URL
const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
const responseImage = await fetch(imageUrl);
const blob = await responseImage.blob();

// Load image - Example 2: From local file (Node.js)
// const fsp = require('fs').promises;
// const imageFileName = "./cat.png";
// const blob = new Blob([await fsp.readFile(imageFileName)]);

// Load image - Example 3: From file input element
// // <input id="image-file" type="file">
// const imageFile = document.getElementById('image-file');
// const blob = imageFile.files[0];

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': blob.type || 'image/jpeg'
  },
  body: blob
});

const result = await response.json();
console.log('Upload result:', result);
console.log('Reference ID:', result.mediaGenerationId.mediaGenerationId);
console.log('Account used:', result.email);
```

**Python**
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'

# Option 1: Without email (auto-selection/load balancing)
api_url = 'https://api.useapi.net/v1/google-flow/assets'

# Option 2: With specific email
# email = 'john@gmail.com'
# api_url = f'https://api.useapi.net/v1/google-flow/assets/{quote(email)}'

# Load image - Example 1: Fetch from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# file_content = response_image.content

# Load image - Example 2: From local file
# image_file_path = "./image.jpg"
# with open(image_file_path, 'rb') as image_file:
#     file_content = image_file.read()

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

response = requests.post(
    api_url,
    headers=headers,
    data=file_content
)

result = response.json()
print('Upload result:', result)
print('Reference ID:', result.get('mediaGenerationId', {}).get('mediaGenerationId'))
print('Account used:', result.get('email'))
```

### Try It

<script>
  async function apiExecutePostGoogleFlowAssetEmail() {
    const tokenElement = document.getElementById('input-token');
    const emailElement = document.getElementById('input-email');
    const inputFile = document.getElementById('input-file');

    if (!inputFile.files[0]) {
      alert('Please select a file.');
      return false;
    }

    const blob = inputFile.files[0];

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': blob.type || 'image/jpeg'
      },
      body: blob
    };

    await apiExecute(
      `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(emailElement.value)}`,
      'input',
      data
    );
  }

  function clearInputFile() {
    document.getElementById('input-file').value = '';
    return false;
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-email"><span>email<small> (optional)</small></span>
        <input id="input-email" type="text" class="input-element" placeholder="john@gmail.com">
      </label>
      <label for="input-file"><span>Upload file</span>
        <div style="display:flex">
          <button id="input-file-clear" onclick="clearInputFile()">✖️</button>
          <input id="input-file" type="file" class="input-element" accept="image/png,image/jpeg,image/webp">
        </div>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowAssetEmail()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale
## Upscale Images
<small>January 2, 2026 (February 14, 2026)</small>

---

Upscale a previously generated image to 2K or 4K resolution. This endpoint uses Google Flow's native image upscaling capabilities.

**Important:**
- Upscaling is only supported for images generated with `nano-banana-pro` and `nano-banana-2` models. Other models (`imagen-4`, `nano-banana`) will return a `429` error.
- `4k` resolution requires a paid Google account with an active subscription. Free accounts can only use `2k` resolution.
> **https://api.useapi.net/v1/google-flow/images/upscale**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "mediaGenerationId": "user:12345-email:6a6f...-image:CAMaJDMx...",
  "resolution": "2k"
}
```

- `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated image via [POST /images](/docs/api-google-flow-v1/post-google-flow-images).
- `resolution` is optional. Target resolution for upscaling (default: `2k`).
  Supported values: `2k`, `4k`.
- `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

**200**
**200 OK**

Image upscaled successfully. Returns base64-encoded image data.

```json
{
  "encodedImage": "/9j/4AAQSkZJRgABAQAAAQ...base64 encoded image data...",
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "abc123...",
    "durationMs": 3500,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "abc123...",
        "durationMs": 3500,
        "success": true
      }
    ]
  }
}
```

**400**
**400 Bad Request**

Invalid request (missing or invalid mediaGenerationId).

```json
{
  "error": "mediaGenerationId is required"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**403**
**403 Forbidden**

Request rejected by Google.

**Recommendations:**
- Ensure `captchaRetry` is set to at least 3 (default). Try increasing to a higher value (e.g., 5) to see if that helps
- If issues persist, contact [useapi.net support](/docs/support)

```json
{
  "error": {
    "code": 403,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_SOMETHING_WENT_WRONG"
      }
    ],
    "message": "reCAPTCHA evaluation failed",
    "status": "PERMISSION_DENIED"
  },
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
    "durationMs": 5789,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
        "durationMs": 5789,
        "success": true
      }
    ]
  }
}
```

**404**
**404 Not Found**

Account not found or image not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**429**
**429 Too Many Requests**

Upscaling not supported for this image. Only images generated with `nano-banana-pro` model can be upscaled.

```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED_UPGRADEABLE",
        "metadata": {
          "canUpgradeForQuota": "true"
        }
      }
    ]
  },
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "e07eb626-a824-40e1-ae03-51a631fbe6ef",
    "durationMs": 3519,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "e07eb626-a824-40e1-ae03-51a631fbe6ef",
        "durationMs": 3519,
        "success": true
      }
    ]
  }
}
```

### Model

- `encodedImage` - Base64-encoded upscaled image data (JPEG format)
- `captcha` - Captcha metadata for debugging/research
- `captcha.service` - Provider that returned the successful token
- `captcha.taskId` - Task ID from the captcha service
- `captcha.durationMs` - Total time for all captcha attempts
- `captcha.attempts` - Array of all captcha attempts (including failures)

```typescript
{
  encodedImage: string                // Base64-encoded image (decode and save as .jpg)
  captcha?: {                         // Captcha metadata
    service: string                   // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
    taskId?: string
    durationMs: number
    attempts: Array<{
      service: string
      taskId?: string
      durationMs: number
      success: boolean
      error?: string
    }>
  }
  error?: string | {                  // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details: Array<{
      '@type': string
      reason: string
    }>
  }
}
```

### Examples

**Curl**
``` bash
# First generate an image
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A beautiful sunset over mountains"}' \
     "https://api.useapi.net/v1/google-flow/images" > generate.json

# Extract mediaGenerationId from the response
MEDIA_ID=$(jq -r '.media[0].image.generatedImage.mediaGenerationId' generate.json)

# Upscale the image to 2K
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"resolution\": \"2k\"}" \
     "https://api.useapi.net/v1/google-flow/images/upscale" > upscale.json

# Decode base64 and save as image
jq -r '.encodedImage' upscale.json | base64 -d > upscaled_image.jpg
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// First generate an image
const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/images', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A beautiful sunset over mountains'
  })
});

const generated = await generateResponse.json();
const mediaGenerationId = generated.media[0].image.generatedImage.mediaGenerationId;

// Upscale the image
const upscaleResponse = await fetch('https://api.useapi.net/v1/google-flow/images/upscale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mediaGenerationId,
    resolution: '2k'
  })
});

const upscaled = await upscaleResponse.json();

// Decode base64 and save
const buffer = Buffer.from(upscaled.encodedImage, 'base64');
require('fs').writeFileSync('upscaled_image.jpg', buffer);
console.log('Upscaled image saved!');
```

**Python**
``` python
import requests
import base64

token = 'YOUR_API_TOKEN'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# First generate an image
generate_response = requests.post(
    'https://api.useapi.net/v1/google-flow/images',
    headers=headers,
    json={'prompt': 'A beautiful sunset over mountains'}
)
generated = generate_response.json()
media_generation_id = generated['media'][0]['image']['generatedImage']['mediaGenerationId']

# Upscale the image
upscale_response = requests.post(
    'https://api.useapi.net/v1/google-flow/images/upscale',
    headers=headers,
    json={
        'mediaGenerationId': media_generation_id,
        'resolution': '2k'
    }
)
upscaled = upscale_response.json()

# Decode base64 and save
image_data = base64.b64decode(upscaled['encodedImage'])
with open('upscaled_image.jpg', 'wb') as f:
    f.write(image_data)
print('Upscaled image saved!')
```

### Try It

<script>
  function displayUpscaledImage(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (!response.encodedImage) {
      mediaContainer.style.display = 'none';
      return;
    }

    const dataUrl = `data:image/jpeg;base64,${response.encodedImage}`;

    const downloadLink = document.createElement('a');
    downloadLink.href = dataUrl;
    downloadLink.download = 'upscaled_image.jpg';
    downloadLink.className = 'media-link image';
    downloadLink.textContent = 'Download Upscaled Image';

    const container = document.createElement('div');
    container.className = 'media-links-container';
    container.innerHTML = '<strong>Upscaled Image:</strong> ';
    container.appendChild(downloadLink);

    const imgPreview = document.createElement('img');
    imgPreview.src = dataUrl;
    imgPreview.style.cssText = 'max-width:100%;margin-top:10px;display:block;border:1px solid #ccc;';
    imgPreview.alt = 'Upscaled image preview';

    mediaContainer.appendChild(container);
    mediaContainer.appendChild(imgPreview);
    mediaContainer.style.display = 'block';
  }

  async function apiExecutePostGoogleFlowImagesUpscale() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'captchaRetry') {
          payload[key] = parseInt(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/images/upscale', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayUpscaledImage(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for image display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-mediaGenerationId"><span>mediaGenerationId<small> (required, from <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>)</small></span>
        <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-image:...">
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="2k">2k (default)</option>
          <option value="4k">4k</option>
        </select>
      </label>
      <label for="input-captchaToken"><span>captchaToken<small> (optional, your own reCAPTCHA token)</small></span>
        <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token">
      </label>
      <label for="input-captchaRetry"><span>captchaRetry<small> (1-10, optional)</small></span>
        <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="3">
      </label>
      <label for="input-captchaOrder"><span>captchaOrder<small> (optional)</small></span>
        <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowImagesUpscale()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images
## Generate Images
<small>November 17, 2025 (May 18, 2026)</small>

---

Generate images using AI models [Imagen 4](https://deepmind.google/technologies/imagen-3/), [Nano Banana / Gemini 2.5 Flash Image](https://deepmind.google/technologies/gemini/flash/), [Nano Banana 2 / Gemini 2.5 Pro Image](https://deepmind.google/technologies/gemini/), and [Nano Banana Pro / Gemini 3 Pro Image](https://deepmind.google/models/gemini-image/pro/) from text prompts with optional reference images. Use any [Google AI](https://one.google.com/ai) subscription or even free account for image generations.

This endpoint features dynamic concurrency management, allowing anywhere from 3 to 20 parallel generations depending on real-time capacity. Image generation typically completes within 10-20 seconds.

### Model Capabilities

| Parameter | [Imagen 4](https://deepmind.google/technologies/imagen-3/)<br/>`imagen-4` (default) | [Nano Banana 2](https://deepmind.google/technologies/gemini/)<br/>`nano-banana-2` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/)<br/>`nano-banana-pro` |
|-----------|:---:|:---:|:---:|
| T2I (text-to-image) | ✓ | ✓ | ✓ |
| I2I (reference images) | ✓ (max 3) | ✓ (max 10) | ✓ (max 10) |
| Aspect ratios | 16:9, 4:3, 1:1, 3:4, 9:16 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> |
| Default aspect ratio | 16:9 | 16:9 (T2I) / auto (I2I) | 16:9 (T2I) / auto (I2I) |
| `count` | ✓ (1-4) | ✓ (1-4) | ✓ (1-4) |
| `seed` | ✓ | ✓ | ✓ |
| Subscription | all | all | all |

<sup>†</sup> `auto` is only valid in image-to-image mode (at least one `reference_*` provided) — the backend derives the aspect ratio from the first reference image.

Legacy alias `nano-banana` is still accepted and maps to `nano-banana-2`.

### Content Moderation

If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts — moderation decisions can vary between requests. Alternatively, switching between `imagen-4`, `nano-banana-2`, and `nano-banana-pro` models may help, as each has different content-moderation behavior.

### Response Codes

#### 429 — Rate limit / quota exhausted

Google returns at least four known distinct `RESOURCE_EXHAUSTED` variants in the response body. Always check the **reason** field on the returned error to pick the right strategy:

| Reason code | What it means | What to do |
|---|---|---|
| `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | **This is a captcha-provider issue, not a useapi.net issue.** Google's reCAPTCHA Enterprise scored the captcha token below its risk threshold — usually because the provider is overloaded or being fingerprinted by Google (the provider's infrastructure is processing too many high-volume requests at once and Google flags them collectively). Our worker has already auto-retried with fresh captcha tokens (up to `captchaRetry` attempts, default 3) before returning this. | **Spread the load across multiple captcha providers** — configure several providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) (e.g. CapSolver + AntiCaptcha + 2Captcha) and use `captchaOrder` on the request to cycle through them. Adding balance to existing providers can also help, since some prioritize higher-balance accounts. As a short-term measure, wait 30-60s and retry, or bump `captchaRetry` higher in the request body. |
| `PUBLIC_ERROR_USER_REQUESTS_THROTTLED` | Google-side per-user concurrency limit. The token was fine; this account is sending too many requests at once. | **Hold for ~hour**, retry after 10-60min. Reduce parallel generations per account. |
| `PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED` | This account hit Google's per-model daily quota. Retrying within the day will not succeed. | **Hold for the day** (quota resets at UTC midnight), or switch to a different model. |
| `PUBLIC_ERROR_USER_QUOTA_REACHED` | This account hit its overall Google Flow quota cap — separate from per-model limits, blocks **all** models on this account. | **Add more Google Flow accounts** via [POST /accounts/`email`](/docs/api-google-flow-v1/post-google-flow-accounts-email) so the load is spread. Hold this specific account until the quota resets, or omit `email` in your request to let load balancing pick a healthier account. |

**Automatic quarantine.** When you omit `email`, the load balancer automatically quarantines an account on any of `PUBLIC_ERROR_USER_QUOTA_REACHED`, `PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED`, or `PUBLIC_ERROR_USER_REQUESTS_THROTTLED` and routes subsequent requests to the remaining healthy accounts. See [Quarantine pre-filter](/docs/api-google-flow-v1/get-google-flow-jobs#step-1--quarantine-pre-filter) for the TTLs and exact behavior.

If every account is quarantined for the requested model, the response is `429` with `error: "no_eligible_account"` plus a `Retry-After` header — see the example payload in the 429 response tab below.

#### 503 — Service unavailable

Transient Google-side issue. Wait 5-10 seconds and retry. If the response body says `"Captcha service failed"`, the issue is with your captcha provider (check API key and balance) rather than Google — don't retry until the provider is back.

#### 403 — Request rejected by Google

Captcha token rejected by Google despite our internal retries — a captcha-provider issue. Increase `captchaRetry` (default 3) in the request body to 5 or higher, and configure additional providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) so `captchaOrder` can cycle across them. If issues persist, contact your reCAPTCHA provider(s) support.
> **https://api.useapi.net/v1/google-flow/images**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A serene mountain landscape at sunset with vibrant colors",
  "model": "imagen-4",
  "aspectRatio": "16:9",
  "count": 4,
  "seed": 123456
}
```

- `email` is optional. The email address of the Google Flow account to use.

  When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **image generation** job statistics to select the healthiest account.

  If reference images (`reference_1` to `_10`) are provided, the `email` parameter can be omitted—the API will automatically use the same account where the images were uploaded.
- `prompt` is **required**, text description for image generation.
- `model` is optional, the AI model to use for image generation (default: `imagen-4`).  
  Supported values: `imagen-4`, `nano-banana-2`, `nano-banana-pro`.
  Legacy alias `nano-banana` is still accepted and maps to `nano-banana-2`.
- `aspectRatio` is optional, output image aspect ratio.
  Supported values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `auto`.
  Legacy aliases `landscape` (→ `16:9`) and `portrait` (→ `9:16`) are still accepted.
  `auto` is only valid with `nano-banana-2` or `nano-banana-pro` **when at least one `reference_*` is provided** — the backend derives the aspect ratio from the first reference image.
  Default:
  - text-to-image (no references): `16:9`
  - `imagen-4` image-to-image: `16:9`
  - `nano-banana-2` / `nano-banana-pro` image-to-image: `auto`
- `count` is optional, number of image variations to generate (1-4, default: `4`).  
- `seed` is optional, random seed for reproducible results (integer ≥ 0).
- `reference_1` to `reference_10` are optional, use `mediaGenerationId` from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for reference images. `imagen-4` supports max 3 references, `nano-banana-2` and `nano-banana-pro` support up to 10.
- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. Callbacks timeout after 5 seconds.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.
- `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

**Auto-detection:** If `model` is not specified: with references selects `nano-banana-2`, without references defaults to `imagen-4`.

### Responses

**200**
**200 OK**

Images generated successfully. Returns job ID and media array with generated image data.

```json
{
  "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow",
  "media": [
    {
      "name": "…redacted…",
      "workflowId": "…redacted…",
      "image": {
        "generatedImage": {
          "seed": 123456,
          "mediaGenerationId": "user:12345…redacted…",
          "mediaVisibility": "PRIVATE",
          "prompt": "A serene mountain landscape at sunset with vibrant colors",
          "modelNameType": "IMAGEN_3_5",
          "workflowId": "…redacted…",
          "fifeUrl": "https://storage.googleapis.com/…redacted…",
          "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE",
          "requestData": {
            "promptInputs": [
              {
                "textInput": "A serene mountain landscape at sunset with vibrant colors"
              }
            ],
            "imageGenerationRequestData": {
              "imageGenerationImageInputs": []
            }
          }
        }
      }
    }
  ],
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "abc123...",
    "durationMs": 3500,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "abc123...",
        "durationMs": 3500,
        "success": true
      }
    ]
  }
}
```

**400**
**400 Bad Request**

Invalid request (validation error, reference count exceeded, email mismatch, or content policy violation).

**General error:**
```json
{
  "error": "Invalid request parameters"
}
```

**Content policy error:**
```json
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_UNSAFE_GENERATION"
      }
    ]
  }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**403**
**403 Forbidden**

Request rejected by Google. See [Response Codes › 403](#403--request-rejected-by-google) above for guidance. Example payload:

```json
{
  "code": 403,
  "created": "2025-12-23T21:54:26.393Z",
  "error": "API error: 403",
  "jobid": "j1223215426393445325i-u12345-email:us***@gmail.com-bot:google-flow",
  "request": {
    "aspectRatio": "portrait",
    "count": 4,
    "email": "us***@gmail.com",
    "model": "nano-banana-pro",
    "prompt": "A serene mountain landscape at sunset",
    "reference_1": {
      "email": "us***@gmail.com",
      "id": "CAMaJDMxZGNl...***...YmUwMmM",
      "referenceId": "user:12345-email:***-image:CAMaJDMxZGNl...***...YmUwMmM",
      "type": "image",
      "user": 12345
    }
  },
  "response": {
    "captcha": {
      "attempts": [
        {
          "service": "AntiCaptcha",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "success": true
        },
        {
          "service": "AntiCaptcha",
          "taskId": "fd044078-0a4a-4303-a585-26fd5d2acb00",
          "durationMs": 5376,
          "success": true
        },
        {
          "service": "AntiCaptcha",
          "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
          "durationMs": 5789,
          "success": true
        }
      ],
      "durationMs": 18091,
      "service": "AntiCaptcha",
      "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42"
    },
    "error": {
      "code": 403,
      "details": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "reason": "PUBLIC_ERROR_SOMETHING_WENT_WRONG"
        }
      ],
      "message": "reCAPTCHA evaluation failed",
      "status": "PERMISSION_DENIED"
    }
  },
  "status": "failed",
  "type": "image",
  "updated": "2025-12-23T21:54:45.319Z"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**429**
**429 Too Many Requests**

Google returns at least four known distinct `RESOURCE_EXHAUSTED` variants. See [Response Codes › 429](#429--rate-limit--quota-exhausted) above for the right strategy per reason. Example payloads:

**Example — reCAPTCHA evaluation failed (`PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC`):**
```json
{
  "error": {
    "code": 429,
    "message": "reCAPTCHA evaluation failed",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC"
      }
    ]
  }
}
```

**Example — per-user throttling:**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_REQUESTS_THROTTLED"
      }
    ]
  }
}
```

**Example — per-model daily quota reached (e.g., using `nano-banana-pro` on non-Ultra account):**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED",
        "metadata": {
          "canUpgradeForQuota": "true"
        }
      }
    ]
  }
}
```

**Example — account-wide quota reached (`PUBLIC_ERROR_USER_QUOTA_REACHED`):**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_QUOTA_REACHED"
      }
    ]
  }
}
```

**Example — every configured account is quarantined for the requested model (`no_eligible_account`):**

When you omit `email` and **every** one of your accounts is currently quarantined for the requested model (see [Quarantine pre-filter](/docs/api-google-flow-v1/get-google-flow-jobs#step-1--quarantine-pre-filter)), the API short-circuits with this `429` response — no upstream call to Google is made. Response headers include `Retry-After: <seconds>` per [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3).

```json
{
  "error": "no_eligible_account",
  "message": "All your Google Flow accounts have hit Google's daily quota for model 'nano-banana-pro'. This quota resets at UTC midnight (2026-05-20T00:00:10.000Z). Try a different model, or wait.",
  "retryAfter": "2026-05-20T00:00:10.000Z",
  "skipReasons": [
    { "email": "alice@gmail.com", "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED", "model": "nano-banana-pro" },
    { "email": "bob@gmail.com",   "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED", "model": "nano-banana-pro" }
  ]
}
```

`skipReasons` lists every account considered and the reason it was filtered, so you can decide whether to wait, switch model, or add more accounts. To bypass the load balancer entirely, specify `email` explicitly — the request will be sent to Google regardless of quarantine state.

**500**
**500 Internal Server Error**

One or more generated images were moderated by Google's content policy. Try one of the following:
- Switch to `imagen-4` model (often successfully processes prompts rejected by `nano-banana`)
- Modify your prompt or remove/change reference images
- Retry the same request (moderation decisions can vary between attempts)

```json
{
  "error": {
    "code": 500,
    "message": "Internal error encountered.",
    "status": "INTERNAL"
  }
}
```

**503**
**503 Service Unavailable**

Service temporarily unavailable or captcha provider error. See [Response Codes › 503](#503--service-unavailable) above for guidance. Example payloads:

```json
{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable.",
    "status": "UNAVAILABLE",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_UNAVAILABLE"
      }
    ]
  }
}
```

```json
{
  "error": "Captcha service failed: ERROR_ZERO_BALANCE",
  "code": 503
}
```

**596**
**596 Session Error**

Google session refresh failed. The account cookies needs to be updated following the instructions in [Setup Google Flow](/docs/start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session."
}
```

### Model

- `jobId` - Unique job identifier (for use with [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid))
- `media` - Array of generated images (1-4 images based on `count`)
- `media[].image.generatedImage` - Generated image data object
- **`generatedImage.fifeUrl`** - **Direct signed URL to access the generated image** (valid for limited time)
- `generatedImage.seed` - Seed used for this generation (for reproducibility)
- `generatedImage.mediaGenerationId` - mediaGenerationId for use in subsequent API calls
- `generatedImage.prompt` - The prompt used for generation
- `generatedImage.modelNameType` - Model variant used (`IMAGEN_3_5`, `R2I`, `GEM_PIX`, `GEM_PIX_2`, `NARWHAL`)
- `generatedImage.aspectRatio` - Generated image aspect ratio (`IMAGE_ASPECT_RATIO_LANDSCAPE`, `IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE`, `IMAGE_ASPECT_RATIO_SQUARE`, `IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR`, or `IMAGE_ASPECT_RATIO_PORTRAIT`)
- `generatedImage.mediaVisibility` - Visibility setting (always "PRIVATE")
- `generatedImage.workflowId` - Unique workflow identifier
- `generatedImage.requestData` - Request data used for this generation including prompt inputs and reference images
- `media[].name` - Internal identifier for the media item
- `media[].workflowId` - Unique workflow identifier for this generation
- `captcha` - Captcha metadata for debugging/research
- `captcha.service` - Provider that returned the successful token
- `captcha.taskId` - Task ID from the captcha service
- `captcha.durationMs` - Total time for all captcha attempts
- `captcha.attempts` - Array of all captcha attempts (including failures)

```typescript
{
  jobId: string                         // Job identifier
  media: Array<{
    name: string                    // Internal media identifier
    workflowId: string              // Unique workflow ID
    image: {
      generatedImage: {
        seed: number
        mediaGenerationId: string   // Format: user:{userid}-email:{hex}-image:{id}
        mediaVisibility: string     // "PRIVATE"
        prompt: string
        modelNameType: string       // "IMAGEN_3_5" | "R2I" | "GEM_PIX" | "GEM_PIX_2" | "NARWHAL"
        workflowId: string
        fifeUrl: string             // Direct signed URL to generated image
        aspectRatio: string         // "IMAGE_ASPECT_RATIO_LANDSCAPE" | "IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE" | "IMAGE_ASPECT_RATIO_SQUARE" | "IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR" | "IMAGE_ASPECT_RATIO_PORTRAIT"
        requestData: {
          promptInputs: Array<{
            textInput: string
          }>
          imageGenerationRequestData: {
            imageGenerationImageInputs: Array<{
              mediaGenerationId: string
              imageInputType: string  // "IMAGE_INPUT_TYPE_REFERENCE"
            }>
          }
        }
      }
    }
  }>
  captcha?: {                       // Captcha metadata
    service: string                 // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
    taskId?: string
    durationMs: number
    attempts: Array<{
      service: string
      taskId?: string
      durationMs: number
      success: boolean
      error?: string
    }>
  }
  error?: string | {                // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details: Array<{
      '@type': string
      reason: string
      metadata?: {
          canUpgradeForQuota: boolean
        }
    }>
  }
  // The following siblings appear only on the load-balancer empty-set 429,
  // i.e. when error === "no_eligible_account" (see 429 response tab).
  message?: string                  // Customer-facing explanation
  retryAfter?: string               // ISO-8601 timestamp of earliest retry
  skipReasons?: Array<{             // Per-account filter rationale
    email: string
    reason: string                  // Google 429 reason that triggered the quarantine
    model: string                   // Quarantined model, or "*" for account-wide
  }>
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A serene mountain landscape at sunset with vibrant colors",
       "model": "imagen-4",
       "aspectRatio": "16:9",
       "count": 4,
       "seed": 123456
     }' \
     "https://api.useapi.net/v1/google-flow/images" > response.json

# Download images using fifeUrl
curl -o image_1.jpg "$(cat response.json | jq -r '.media[0].image.generatedImage.fifeUrl')"
curl -o image_2.jpg "$(cat response.json | jq -r '.media[1].image.generatedImage.fifeUrl')"
# Continue for remaining images...
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const apiUrl = 'https://api.useapi.net/v1/google-flow/images';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset with vibrant colors',
    model: 'imagen-4',
    aspectRatio: '16:9',
    count: 4,
    seed: 123456
  })
});

const result = await response.json();
console.log('Generated images:', result.media.length);

// Download and save images
for (const [index, item] of result.media.entries()) {
  const img = item.image.generatedImage;
  console.log(`Image ${index + 1} seed:`, img.seed);
  console.log(`mediaGenerationId:`, img.mediaGenerationId);

  // Download image from fifeUrl
  const imageResponse = await fetch(img.fifeUrl);
  const imageBlob = await imageResponse.blob();

  // In Node.js with fs:
  // const buffer = Buffer.from(await imageBlob.arrayBuffer());
  // require('fs').writeFileSync(`generated_image_${index + 1}.jpg`, buffer);

  // In browser: create download link or display in <img> element
  // const url = URL.createObjectURL(imageBlob);
  // document.querySelector('img').src = url;
}
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
api_url = 'https://api.useapi.net/v1/google-flow/images'

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

data = {
    'prompt': 'A serene mountain landscape at sunset with vibrant colors',
    'model': 'imagen-4',
    'aspectRatio': '16:9',
    'count': 4,
    'seed': 123456
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()

print(f"Generated {len(result['media'])} images")

# Download and save images
for index, item in enumerate(result['media']):
    img = item['image']['generatedImage']
    print(f"Image {index + 1} seed:", img['seed'])
    print(f"mediaGenerationId:", img['mediaGenerationId'])

    # Download image from fifeUrl
    image_response = requests.get(img['fifeUrl'])
    with open(f'generated_image_{index + 1}.jpg', 'wb') as f:
        f.write(image_response.content)
```

### Try It

<script>
  function displayGoogleFlowImages(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (!response.media || response.media.length === 0) {
      mediaContainer.style.display = 'none';
      return;
    }

    const images = [];
    response.media.forEach((item, index) => {
      if (item.image?.generatedImage) {
        const img = item.image.generatedImage;
        images.push({
          url: img.fifeUrl,
          seed: img.seed,
          label: `Image ${index + 1}${img.seed ? ` (seed: ${img.seed})` : ''}`
        });
      }
    });

    if (images.length > 0) {
      const linksHTML = images.map(img =>
        `<a href="${img.url}" target="_blank" rel="noopener noreferrer" class="media-link image">${img.label}</a>`
      ).join(' ');

      mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Images:</strong> ${linksHTML}</div>`;
      mediaContainer.style.display = 'block';
    } else {
      mediaContainer.style.display = 'none';
    }
  }

  async function apiExecutePostGoogleFlowImages() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'seed' || key === 'count' || key === 'captchaRetry') {
          payload[key] = parseInt(value);
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/images', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayGoogleFlowImages(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for image display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-email"><span>email<small> (optional)</small></span>
        <input id="input-email" type="text" class="input-element input-query-param" placeholder="john@gmail.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="A serene mountain landscape">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="imagen-4">imagen-4 (default)</option>
          <option value="nano-banana-2">nano-banana-2</option>
          <option value="nano-banana-pro">nano-banana-pro</option>
        </select>
      </label>
      <label for="input-aspectRatio"><span>aspectRatio</span>
        <select id="input-aspectRatio" class="input-element input-query-param">
          <option value="">(default — auto for nano-banana image-to-image, otherwise 16:9)</option>
          <option value="16:9">16:9</option>
          <option value="4:3">4:3</option>
          <option value="1:1">1:1</option>
          <option value="3:4">3:4</option>
          <option value="9:16">9:16</option>
          <option value="auto">auto (nano-banana image-to-image only)</option>
        </select>
      </label>
      <label for="input-count"><span>count</span>
        <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="4">
      </label>
      <label for="input-seed"><span>seed</span>
        <input id="input-seed" type="number" class="input-element input-query-param" min="0" placeholder="(random)">
      </label>
      <label for="input-reference_1"><span>reference_1<small> (optional, from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a>)</small></span>
        <input id="input-reference_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_2"><span>reference_2</span>
        <input id="input-reference_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_3"><span>reference_3</span>
        <input id="input-reference_3" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_4"><span>reference_4<small> (nano-banana-2 / nano-banana-pro only)</small></span>
        <input id="input-reference_4" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_5"><span>reference_5</span>
        <input id="input-reference_5" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_6"><span>reference_6</span>
        <input id="input-reference_6" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_7"><span>reference_7</span>
        <input id="input-reference_7" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_8"><span>reference_8</span>
        <input id="input-reference_8" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_9"><span>reference_9</span>
        <input id="input-reference_9" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-reference_10"><span>reference_10</span>
        <input id="input-reference_10" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
      <label for="input-captchaToken"><span>captchaToken<small> (optional, your own reCAPTCHA token)</small></span>
        <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token">
      </label>
      <label for="input-captchaRetry"><span>captchaRetry<small> (1-10, optional)</small></span>
        <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="3">
      </label>
      <label for="input-captchaOrder"><span>captchaOrder<small> (optional)</small></span>
        <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowImages()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-concatenate ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-concatenate
## Concatenate Videos
<small>January 29, 2026</small>

---

Concatenate multiple previously generated videos into a single video. This is a synchronous operation that returns base64-encoded video data.

- Combines 2-10 videos into a single video file.
- All videos must have the same aspect ratio (all landscape or all portrait).
- No captcha required - this endpoint doesn't require reCAPTCHA solving.
- Optional trimming allows removing frames from the start/end of each video for smoother transitions.
- Returns large base64-encoded video data (~7MB per input video).
- Concatenation typically completes within 15-20 seconds.
> **https://api.useapi.net/v1/google-flow/videos/concatenate**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "media": [
    { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx..." },
    { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMy...", "trimStart": 0.5 },
    { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMz...", "trimEnd": 1 }
  ]
}
```

- `media` is **required**. Array of 2-10 video references to concatenate. Each item contains:
  - `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated or extended video.
  - `trimStart` is optional. Seconds to trim from the start of this video (0-8, default: 0). When concatenating extended videos, use `trimStart: 1` to remove the ~1 second overlap with the source video.
  - `trimEnd` is optional. Seconds to trim from the end of this video (0-8, default: 0).

**Notes:**
- All videos must belong to the same Google Flow account (same email).
- All videos must have the same aspect ratio.
- Videos are concatenated in the order provided.

### Responses

**200**
**200 OK**

Videos concatenated successfully. Returns job ID and base64-encoded video data.

```json
{
  "jobId": "j1737312345678v-u12345-email:jo***@gmail.com-bot:google-flow",
  "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL",
  "inputsCount": 3,
  "encodedVideo": "AAAAIGZ0eXBpc29t...~21MB base64..."
}
```

**400**
**400 Bad Request**

Invalid request.

```json
{
  "error": "Error message",
  "code": 400
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**408**
**408 Request Timeout**

Concatenation polling timeout (after 3 minutes).

```json
{
  "error": "Polling timeout"
}
```

### Model

```typescript
{
  jobId: string                    // Job identifier
  status: string                   // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
  inputsCount: number              // Number of input videos
  encodedVideo: string             // Base64-encoded MP4 (~7MB per input, decode and save as .mp4)
  error?: string | {               // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details?: Array<{
      '@type': string
      reason: string
    }>
  }
}
```

### Examples

**Curl**
``` bash
# Generate first video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A serene mountain landscape at sunrise"}' \
     "https://api.useapi.net/v1/google-flow/videos" > video1.json

# Generate second video (or extend the first)
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "The sun rises higher, birds fly across the sky"}' \
     "https://api.useapi.net/v1/google-flow/videos" > video2.json

# Extract mediaGenerationIds
VIDEO1_ID=$(jq -r '.operations[0].mediaGenerationId' video1.json)
VIDEO2_ID=$(jq -r '.operations[0].mediaGenerationId' video2.json)

# Concatenate videos
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"media\": [{\"mediaGenerationId\": \"$VIDEO1_ID\"}, {\"mediaGenerationId\": \"$VIDEO2_ID\", \"trimStart\": 0.5}]}" \
     "https://api.useapi.net/v1/google-flow/videos/concatenate" > concat.json

# Decode base64 and save as MP4
jq -r '.encodedVideo' concat.json | base64 -d > concatenated_video.mp4
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// Assume you have two video mediaGenerationIds
const videoId1 = 'user:12345-email:6a6f...-video:CAMaJDMx...';
const videoId2 = 'user:12345-email:6a6f...-video:CAMaJDMy...';

// Concatenate videos
const concatResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/concatenate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    media: [
      { mediaGenerationId: videoId1 },
      { mediaGenerationId: videoId2, trimStart: 0.5 }  // Trim 0.5s from start for smooth transition
    ]
  })
});

const result = await concatResponse.json();

// Decode base64 and save (Node.js)
const buffer = Buffer.from(result.encodedVideo, 'base64');
require('fs').writeFileSync('concatenated_video.mp4', buffer);
console.log('Concatenated video saved!');

// Or use in browser as data URL for preview
const dataUrl = `data:video/mp4;base64,${result.encodedVideo}`;
document.getElementById('video-player').src = dataUrl;
```

**Python**
``` python
import requests
import base64

token = 'YOUR_API_TOKEN'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# Assume you have two video mediaGenerationIds
video_id_1 = 'user:12345-email:6a6f...-video:CAMaJDMx...'
video_id_2 = 'user:12345-email:6a6f...-video:CAMaJDMy...'

# Concatenate videos
concat_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos/concatenate',
    headers=headers,
    json={
        'media': [
            {'mediaGenerationId': video_id_1},
            {'mediaGenerationId': video_id_2, 'trimStart': 0.5}  # Trim 0.5s for smooth transition
        ]
    }
)
result = concat_response.json()

# Decode base64 and save
video_data = base64.b64decode(result['encodedVideo'])
with open('concatenated_video.mp4', 'wb') as f:
    f.write(video_data)
print(f'Concatenated video saved! ({len(video_data)} bytes)')
```

### Try It

<script>
  function displayConcatenatedVideo(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (!response.encodedVideo) {
      mediaContainer.style.display = 'none';
      return;
    }

    const dataUrl = `data:video/mp4;base64,${response.encodedVideo}`;

    const downloadLink = document.createElement('a');
    downloadLink.href = dataUrl;
    downloadLink.download = 'concatenated_video.mp4';
    downloadLink.className = 'media-link video';
    downloadLink.textContent = 'Download Concatenated Video';

    const container = document.createElement('div');
    container.className = 'media-links-container';
    container.innerHTML = '<strong>Concatenated Video:</strong> ';
    container.appendChild(downloadLink);

    mediaContainer.appendChild(container);
    mediaContainer.style.display = 'block';
  }

  async function apiExecutePostGoogleFlowVideosConcatenate() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const media = [];
    for (let i = 1; i <= 5; i++) {
      const idInput = document.getElementById(`input-mediaGenerationId-${i}`);
      const trimStartInput = document.getElementById(`input-trimStart-${i}`);
      const trimEndInput = document.getElementById(`input-trimEnd-${i}`);

      if (idInput && idInput.value?.trim()) {
        const item = { mediaGenerationId: idInput.value.trim() };
        if (trimStartInput && trimStartInput.value) {
          item.trimStart = parseFloat(trimStartInput.value);
        }
        if (trimEndInput && trimEndInput.value) {
          item.trimEnd = parseFloat(trimEndInput.value);
        }
        media.push(item);
      }
    }

    const payload = { media };

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/concatenate', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayConcatenatedVideo(response, elementId);
        if (response.encodedVideo) {
          const trimmed = { ...response, encodedVideo: response.encodedVideo.slice(0, 50) + '...' };
          content.innerText = JSON.stringify(trimmed, null, 2);
        }
      } catch (e) {
        console.error('Failed to parse response for video display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-mediaGenerationId-1"><span>Video 1️⃣ mediaGenerationId<small> (required)</small></span>
        <input id="input-mediaGenerationId-1" type="text" class="input-element" required aria-required="true" placeholder="user:123-email:...-video:...">
      </label>
      <div style="display: flex; gap: 10px;">
        <label for="input-trimStart-1" style="flex:1;"><span>trimStart (seconds)</span>
          <input id="input-trimStart-1" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
        <label for="input-trimEnd-1" style="flex:1;"><span>trimEnd (seconds)</span>
          <input id="input-trimEnd-1" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
      </div>
      <label for="input-mediaGenerationId-2"><span>Video 2️⃣ mediaGenerationId<small> (required)</small></span>
        <input id="input-mediaGenerationId-2" type="text" class="input-element" required aria-required="true" placeholder="user:123-email:...-video:...">
      </label>
      <div style="display: flex; gap: 10px;">
        <label for="input-trimStart-2" style="flex:1;"><span>trimStart (seconds)</span>
          <input id="input-trimStart-2" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
        <label for="input-trimEnd-2" style="flex:1;"><span>trimEnd (seconds)</span>
          <input id="input-trimEnd-2" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
      </div>
      <label for="input-mediaGenerationId-3"><span>Video 3️⃣ mediaGenerationId<small> (optional)</small></span>
        <input id="input-mediaGenerationId-3" type="text" class="input-element" placeholder="user:123-email:...-video:...">
      </label>
      <div style="display: flex; gap: 10px;">
        <label for="input-trimStart-3" style="flex:1;"><span>trimStart (seconds)</span>
          <input id="input-trimStart-3" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
        <label for="input-trimEnd-3" style="flex:1;"><span>trimEnd (seconds)</span>
          <input id="input-trimEnd-3" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
      </div>
      <label for="input-mediaGenerationId-4"><span>Video 4️⃣ mediaGenerationId<small> (optional)</small></span>
        <input id="input-mediaGenerationId-4" type="text" class="input-element" placeholder="user:123-email:...-video:...">
      </label>
      <div style="display: flex; gap: 10px;">
        <label for="input-trimStart-4" style="flex:1;"><span>trimStart (seconds)</span>
          <input id="input-trimStart-4" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
        <label for="input-trimEnd-4" style="flex:1;"><span>trimEnd (seconds)</span>
          <input id="input-trimEnd-4" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
      </div>
      <label for="input-mediaGenerationId-5"><span>Video 5️⃣ mediaGenerationId<small> (optional)</small></span>
        <input id="input-mediaGenerationId-5" type="text" class="input-element" placeholder="user:123-email:...-video:...">
      </label>
      <div style="display: flex; gap: 10px;">
        <label for="input-trimStart-5" style="flex:1;"><span>trimStart (seconds)</span>
          <input id="input-trimStart-5" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
        <label for="input-trimEnd-5" style="flex:1;"><span>trimEnd (seconds)</span>
          <input id="input-trimEnd-5" type="number" class="input-element" min="0" max="8" step="0.1" placeholder="0">
        </label>
      </div>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosConcatenate()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-extend ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-extend
## Extend Videos
<small>January 29, 2026 (May 11, 2026)</small>

---

Extend a previously generated video with a new prompt. Creates an additional 8-second segment that continues from the last ~1 second of the source video.

- Video extension requires a paid [Google AI](https://one.google.com/ai) subscription with remaining credits.
- The extended video inherits the aspect ratio from the source video (landscape or portrait).
- Extended videos have ~1 second overlap with the source video's last frame. Use `trimStart` in [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) to remove overlap when combining clips.
> **https://api.useapi.net/v1/google-flow/videos/extend**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...",
  "prompt": "The camera slowly pans right revealing a majestic waterfall"
}
```

- `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated or extended video via [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) or [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend).
- `prompt` is **required**. Text description for the video extension (what happens next).
- `model` is optional. Video generation model (default: `veo-3.1-fast`).
  Supported values: `veo-3.1-fast`, `veo-3.1-quality`, `veo-3.1-lite`, `veo-3.1-lite-low-priority` (Ultra only, no credits, lower priority).
- `count` is optional. Number of video variations to generate (1-4, default: 1). Each variation uses a different seed.
- `seed` is optional. Random seed for reproducible results. If not specified, a random seed is generated. When `count` > 1, seeds are incremented (seed, seed+1, seed+2, ...).
- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status.
- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

**200**
**200 OK**

Video extended successfully. Returns job ID, media array with video data, and operations array (deprecated) with extended video URLs.

```json
{
  "jobId": "j1737312345678v-u12345-email:jo***@gmail.com-bot:google-flow",
  "media": [
    {
      "name": "CAUSJ...redacted...OWQ5ZA",
      "projectId": "...redacted...",
      "mediaMetadata": {
        "mediaStatus": {
          "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
        }
      },
      "video": {
        "generatedVideo": {
          "seed": 987654321,
          "model": "veo_3_1_t2v",
          "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
          "isLooped": false,
          "prompt": "The camera slowly pans right revealing a majestic waterfall"
        },
        "operation": {
          "name": "d00af...redacted...6f7a"
        }
      },
      "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
      "videoUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted..."
    }
  ],
  "operations": [
    {
      "operation": {
        "name": "d00af...redacted...6f7a",
        "metadata": {
          "@type": "type.googleapis.com/google.internal.labs.aisandbox.v1.Media",
          "name": "CAUSJ...redacted...OWQ5ZA",
          "video": {
            "seed": 987654321,
            "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
            "prompt": "The camera slowly pans right revealing a majestic waterfall",
            "fifeUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted...",
            "mediaVisibility": "PRIVATE",
            "servingBaseUri": "https://storage.googleapis.com/ai-sandbox-videofx/image/...redacted...",
            "model": "veo_3_1_t2v",
            "isLooped": false,
            "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
          }
        }
      },
      "sceneId": "323c0...redacted...3ebf6",
      "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
      "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
    }
  ],
  "remainingCredits": 18760,
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "abc123...",
    "durationMs": 3500,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "abc123...",
        "durationMs": 3500,
        "success": true
      }
    ]
  }
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Video extension is processing in the background.

Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status.

```json
{
  "jobid": "j1737312345678v-u12345-email:jo***@gmail.com-bot:google-flow",
  "type": "video",
  "status": "created",
  "created": "2026-01-29T12:34:56.789Z",
  "request": {
    "async": true,
    "prompt": "The camera slowly pans right revealing a majestic waterfall",
    "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx..."
  },
  "response": {
    "operations": [
      {
        "operation": {
          "name": "1450903d...redacted...9c86f0"
        },
        "sceneId": "1450903d...redacted...9c86f0",
        "status": "MEDIA_GENERATION_STATUS_PENDING"
      }
    ],
    "captcha": {
      "service": "AntiCaptcha",
      "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
      "durationMs": 5357
    }
  }
}
```

**400**
**400 Bad Request**

Invalid request.

```json
{
  "error": "Error message",
  "code": 400
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**403**
**403 Forbidden**

Request rejected by Google.

**Recommendations:**
- Ensure `captchaRetry` is set to at least 3 (default). Try increasing to a higher value (e.g., 5) to see if that helps
- If issues persist, contact [useapi.net support](/docs/support)

```json
{
  "error": {
    "code": 403,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_SOMETHING_WENT_WRONG"
      }
    ],
    "message": "reCAPTCHA evaluation failed",
    "status": "PERMISSION_DENIED"
  }
}
```

**404**
**404 Not Found**

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**408**
**408 Request Timeout**

Video extension polling timeout (after 10 minutes).

```json
{
  "error": "Polling timeout"
}
```

### Model

**200 OK (Sync)**

Video extension completed. Returns extended video data with signed URLs.

```typescript
{
  jobId: string                              // Job identifier
  media: Array<{                             // Preferred — use this instead of operations
    name: string                             // Media identifier (raw UUID)
    projectId: string
    mediaMetadata: {
      mediaStatus: {
        mediaGenerationStatus: string        // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
        error?: { code: number; message: string }
      }
      visibility?: string
    }
    video?: {
      generatedVideo: {
        seed: number
        model: string                        // veo_3_1_t2v
        aspectRatio: string                  // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        isLooped: boolean
        prompt?: string
      }
      operation: { name: string }
    }
    mediaGenerationId: string                // Encoded reference ID for use in subsequent API calls
    videoUrl?: string                        // Signed video download URL (MP4, valid ~24h)
  }>
  operations: Array<{                        // Deprecated — will be removed in a future release
    operation?: {
      name: string
      metadata: {
        '@type': string
        name: string
        video: {
          seed: number
          mediaGenerationId: string          // Reference ID for the extended video
          prompt: string                     // Extension prompt
          fifeUrl: string                    // Signed video URL (MP4, valid ~24h)
          mediaVisibility: string
          servingBaseUri: string             // Signed thumbnail URL (JPEG, valid ~24h)
          model: string                      // veo_3_1_t2v
          isLooped: boolean
          aspectRatio: string                // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        }
      }
    }
    sceneId: string
    mediaGenerationId: string
    status: string                           // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
  }>
  remainingCredits?: number
  captcha?: {                                // Captcha metadata
    service: string                          // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
    taskId?: string
    durationMs: number
    attempts: Array<{
      service: string
      taskId?: string
      durationMs: number
      success: boolean
      error?: string
    }>
  }
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.

```typescript
{
  jobid: string                              // Job identifier
  type: 'video'                              // Job type
  status: 'created'                          // Job status
  created: string                            // ISO 8601 timestamp
  request: {
    async: true
    prompt: string                           // Extension prompt
    mediaGenerationId: string                // Source video reference
    model?: string                           // "veo-3.1-fast"
    seed?: number
    replyUrl?: string
    replyRef?: string
  }
  response: {
    operations: Array<{
      operation: {
        name: string                         // Operation identifier
      }
      sceneId: string                        // Scene identifier
      status: 'MEDIA_GENERATION_STATUS_PENDING'
    }>
    captcha?: {                              // Present when captcha was used
      service: string                        // Provider or "UserProvided"
      taskId?: string                        // Absent for UserProvided
      durationMs: number
    }
  }
}
```

**Error**

Error response structure.

```typescript
{
  jobId?: string                             // Present for job-related errors
  error: string                              // Error summary message
  code?: number                              // HTTP status code
  response?: {                               // API response with error details
    error?: {
      code: number
      message: string
      status: string
      details?: Array<{
        '@type': string
        reason: string
      }>
    }
  }
}
```

### Examples

**Curl**
``` bash
# First generate a video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A serene mountain landscape at sunset"}' \
     "https://api.useapi.net/v1/google-flow/videos" > generate.json

# Extract mediaGenerationId from the response (prefer media[] over deprecated operations[])
MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json)

# Extend the video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"prompt\": \"The camera slowly pans right revealing a majestic waterfall\"}" \
     "https://api.useapi.net/v1/google-flow/videos/extend" > extend.json

# Extract extended video URL and download (prefer media[] over deprecated operations[])
VIDEO_URL=$(jq -r '.media[0].videoUrl' extend.json)
curl "$VIDEO_URL" --output extended_video.mp4
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// First generate a video
const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset'
  })
});

const generated = await generateResponse.json();
// Prefer media[] over deprecated operations[]
const mediaGenerationId = generated.media[0].mediaGenerationId;

// Extend the video
const extendResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/extend', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mediaGenerationId,
    prompt: 'The camera slowly pans right revealing a majestic waterfall'
  })
});

const extended = await extendResponse.json();
// Prefer media[] over deprecated operations[]
const videoUrl = extended.media[0].videoUrl;

// Download extended video (Node.js)
const videoResponse = await fetch(videoUrl);
const videoBuffer = await videoResponse.arrayBuffer();
require('fs').writeFileSync('extended_video.mp4', Buffer.from(videoBuffer));
console.log('Extended video saved!');
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# First generate a video
generate_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos',
    headers=headers,
    json={'prompt': 'A serene mountain landscape at sunset'}
)
generated = generate_response.json()
# Prefer media[] over deprecated operations[]
media_generation_id = generated['media'][0]['mediaGenerationId']

# Extend the video
extend_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos/extend',
    headers=headers,
    json={
        'mediaGenerationId': media_generation_id,
        'prompt': 'The camera slowly pans right revealing a majestic waterfall'
    }
)
extended = extend_response.json()
# Prefer media[] over deprecated operations[]
video_url = extended['media'][0]['videoUrl']

# Download extended video
video_response = requests.get(video_url)
with open('extended_video.mp4', 'wb') as f:
    f.write(video_response.content)
print('Extended video saved!')
```

### Try It

<script>
  function displayExtendedVideo(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    const mediaItems = response.media || [];
    const operations = response.operations || [];
    if (mediaItems.length === 0 && operations.length === 0) {
      mediaContainer.style.display = 'none';
      return;
    }

    const videos = [];
    if (mediaItems.length > 0) {
      mediaItems.forEach((item, index) => {
        videos.push({
          videoUrl: item.videoUrl,
          label: `Extended Video`
        });
      });
    } else {
      operations.forEach((op, index) => {
        if (op.operation?.metadata?.video) {
          const video = op.operation.metadata.video;
          videos.push({
            videoUrl: video.fifeUrl,
            label: `Extended Video`
          });
        }
      });
    }

    if (videos.length > 0) {
      const linksHTML = videos.map(vid => {
        return `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`;
      }).join(' ');

      mediaContainer.innerHTML = `<div class="media-links-container"><strong>Extended Video:</strong> ${linksHTML}</div>`;
      mediaContainer.style.display = 'block';
    } else {
      mediaContainer.style.display = 'none';
    }
  }

  async function apiExecutePostGoogleFlowVideosExtend() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'captchaRetry' || key === 'seed' || key === 'count') {
          payload[key] = parseInt(value);
        } else if (key === 'async') {
          payload[key] = value === 'true';
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/extend', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayExtendedVideo(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for video display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-mediaGenerationId"><span>mediaGenerationId<small> (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> or <a href="/docs/api-google-flow-v1/post-google-flow-videos-extend">POST /videos/extend</a>)</small></span>
        <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:...">
      </label>
      <label for="input-prompt"><span>prompt<small> (required)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="The camera slowly pans right...">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="">veo-3.1-fast (default)</option>
          <option value="veo-3.1-fast">veo-3.1-fast</option>
          <option value="veo-3.1-quality">veo-3.1-quality</option>
          <option value="veo-3.1-lite">veo-3.1-lite</option>
          <option value="veo-3.1-lite-low-priority">veo-3.1-lite-low-priority (Ultra only, no credits, lower priority)</option>
        </select>
      </label>
      <label for="input-count"><span>count<small> (1-4, default: 1)</small></span>
        <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="1">
      </label>
      <label for="input-seed"><span>seed<small> (optional)</small></span>
        <input id="input-seed" type="number" class="input-element input-query-param" placeholder="Random if not specified">
      </label>
      <label for="input-async"><span>async<small> (fire-and-forget mode)</small></span>
        <select id="input-async" class="input-element input-query-param">
          <option value="false">false (default)</option>
          <option value="true">true</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
      <label for="input-captchaToken"><span>captchaToken<small> (optional, your own reCAPTCHA token)</small></span>
        <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token">
      </label>
      <label for="input-captchaRetry"><span>captchaRetry<small> (1-10, optional)</small></span>
        <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="3">
      </label>
      <label for="input-captchaOrder"><span>captchaOrder<small> (optional)</small></span>
        <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosExtend()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-gif ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-gif
## Generate Video GIF
<small>January 20, 2026</small>

---

Generate an animated GIF preview from a previously generated video. This is a synchronous operation that returns base64-encoded GIF data.

- No captcha required - this endpoint doesn't require reCAPTCHA solving.
- GIF generation can take up to 90 seconds.
> **https://api.useapi.net/v1/google-flow/videos/gif**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx..."
}
```

- `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated video via [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos).

### Responses

**200**
**200 OK**

GIF generated successfully. Returns base64-encoded GIF data.

```json
{
  "encodedGif": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7...base64 encoded GIF data..."
}
```

**400**
**400 Bad Request**

Invalid request (missing or invalid mediaGenerationId).

```json
{
  "error": "mediaGenerationId is required"
}
```

**Invalid reference type:**
```json
{
  "error": "mediaGenerationId type must be 'video', got 'image'"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

### Model

```typescript
{
  encodedGif: string                // Base64-encoded GIF data (decode and save as .gif)
  error?: string | {                // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details?: Array<{
      '@type': string
      reason: string
    }>
  }
}
```

### Examples

**Curl**
``` bash
# First generate a video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A serene mountain landscape at sunset"}' \
     "https://api.useapi.net/v1/google-flow/videos" > generate.json

# Extract mediaGenerationId from the response
MEDIA_ID=$(jq -r '.operations[0].mediaGenerationId' generate.json)

# Generate GIF preview
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"mediaGenerationId\": \"$MEDIA_ID\"}" \
     "https://api.useapi.net/v1/google-flow/videos/gif" > gif.json

# Decode base64 and save as GIF
jq -r '.encodedGif' gif.json | base64 -d > video_preview.gif
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// First generate a video
const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset'
  })
});

const generated = await generateResponse.json();
const mediaGenerationId = generated.operations[0].mediaGenerationId;

// Generate GIF preview
const gifResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/gif', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ mediaGenerationId })
});

const gifResult = await gifResponse.json();

// Decode base64 and save (Node.js)
const buffer = Buffer.from(gifResult.encodedGif, 'base64');
require('fs').writeFileSync('video_preview.gif', buffer);
console.log('GIF preview saved!');

// Or use in browser as data URL
const dataUrl = `data:image/gif;base64,${gifResult.encodedGif}`;
document.getElementById('preview').src = dataUrl;
```

**Python**
``` python
import requests
import base64

token = 'YOUR_API_TOKEN'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# First generate a video
generate_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos',
    headers=headers,
    json={'prompt': 'A serene mountain landscape at sunset'}
)
generated = generate_response.json()
media_generation_id = generated['operations'][0]['mediaGenerationId']

# Generate GIF preview
gif_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos/gif',
    headers=headers,
    json={'mediaGenerationId': media_generation_id}
)
gif_result = gif_response.json()

# Decode base64 and save
gif_data = base64.b64decode(gif_result['encodedGif'])
with open('video_preview.gif', 'wb') as f:
    f.write(gif_data)
print('GIF preview saved!')
```

### Try It

<script>
  function displayVideoGif(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    if (!response.encodedGif) {
      mediaContainer.style.display = 'none';
      return;
    }

    const dataUrl = `data:image/gif;base64,${response.encodedGif}`;

    const downloadLink = document.createElement('a');
    downloadLink.href = dataUrl;
    downloadLink.download = 'video_preview.gif';
    downloadLink.className = 'media-link image';
    downloadLink.textContent = 'Download GIF';

    const container = document.createElement('div');
    container.className = 'media-links-container';
    container.innerHTML = '<strong>Video GIF Preview:</strong> ';
    container.appendChild(downloadLink);

    const imgPreview = document.createElement('img');
    imgPreview.src = dataUrl;
    imgPreview.style.cssText = 'max-width:100%;margin-top:10px;display:block;border:1px solid #ccc;';
    imgPreview.alt = 'GIF preview';

    mediaContainer.appendChild(container);
    mediaContainer.appendChild(imgPreview);
    mediaContainer.style.display = 'block';
  }

  async function apiExecutePostGoogleFlowVideosGif() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        payload[key] = value;
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/gif', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayVideoGif(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for GIF display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-mediaGenerationId"><span>mediaGenerationId<small> (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>)</small></span>
        <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:...">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosGif()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-upscale ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-upscale
## Upscale Videos
<small>January 20, 2026 (February 27, 2026)</small>

---

Upscale a previously generated video to 1080p or 4K resolution.

- Currently, video upscaling requires a paid [Google AI](https://one.google.com/ai) subscription or remaining credits.
- Currently, `4K` resolution requires a [Google AI Ultra](https://one.google.com/ai) subscription. Other paid accounts can only use `1080p` resolution.
- `1080p` upscaling is free. `4K` upscaling currently costs 50 credits.
- Video upscaling typically completes within 30-60 seconds, with 4K taking a few minutes.
- Upscaling the same video twice returns a cached result (no additional credits consumed). Use the video URL from the first upscale response.
> **https://api.useapi.net/v1/google-flow/videos/upscale**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...",
  "resolution": "1080p"
}
```

- `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated video via [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos).
- `resolution` is optional. Target resolution for upscaling (default: `1080p`).  
  Supported values: `1080p`, `4K`.
- `async` is optional, enables fire-and-forget mode (default: `false`).  
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status.
- `replyUrl` is optional, webhook URL for job status callbacks.  
  Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

**200**
**200 OK**

Video upscaled successfully. Returns job ID, media array with video data, and operations array (deprecated) with upscaled video URLs.

```json
{
  "jobId": "j1737312345678v-u12345-email:jo***@gmail.com-bot:google-flow",
  "media": [
    {
      "name": "CAUSJ...redacted...OWQ5ZA",
      "projectId": "...redacted...",
      "mediaMetadata": {
        "mediaStatus": {
          "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
        }
      },
      "video": {
        "generatedVideo": {
          "seed": 987654321,
          "model": "veo_3_1_upsampler_1080p",
          "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
          "isLooped": false
        },
        "operation": {
          "name": "d00af...redacted...6f7a"
        }
      },
      "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
      "videoUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted..."
    }
  ],
  "operations": [
    {
      "operation": {
        "name": "d00af...redacted...6f7a",
        "metadata": {
          "@type": "type.googleapis.com/google.internal.labs.aisandbox.v1.Media",
          "name": "CAUSJ...redacted...OWQ5ZA",
          "video": {
            "seed": 987654321,
            "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
            "prompt": "Original video prompt",
            "fifeUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted...",
            "mediaVisibility": "PRIVATE",
            "servingBaseUri": "https://storage.googleapis.com/ai-sandbox-videofx/image/...redacted...",
            "model": "veo_3_1_upsampler_1080p",
            "isLooped": false,
            "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
          }
        }
      },
      "sceneId": "323c0...redacted...3ebf6",
      "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
      "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
    }
  ],
  "remainingCredits": 18760,
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "abc123...",
    "durationMs": 3500,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "abc123...",
        "durationMs": 3500,
        "success": true
      }
    ]
  }
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Video upscaling is processing in the background.

Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status.

```json
{
  "jobid": "j1737312345678v-u12345-email:jo***@gmail.com-bot:google-flow",
  "type": "video",
  "status": "created",
  "created": "2026-01-19T12:34:56.789Z",
  "request": {
    "async": true,
    "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...",
    "resolution": "1080p"
  },
  "response": {
    "operations": [
      {
        "operation": {
          "name": "1450903d...redacted...9c86f0"
        },
        "sceneId": "1450903d...redacted...9c86f0",
        "status": "MEDIA_GENERATION_STATUS_PENDING"
      }
    ],
    "captcha": {
      "service": "AntiCaptcha",
      "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
      "durationMs": 5357
    }
  }
}
```

**400**
**400 Bad Request**

Invalid request.

```json
{
  "error": "Error message"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**403**
**403 Forbidden**

Request rejected by Google.

**Recommendations:**
- Ensure `captchaRetry` is set to at least 3 (default). Try increasing to a higher value (e.g., 5) to see if that helps
- If issues persist, contact [useapi.net support](/docs/support)

```json
{
  "error": {
    "code": 403,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_SOMETHING_WENT_WRONG"
      }
    ],
    "message": "reCAPTCHA evaluation failed",
    "status": "PERMISSION_DENIED"
  },
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
    "durationMs": 5789,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
        "durationMs": 5789,
        "success": true
      }
    ]
  }
}
```

**404**
**404 Not Found**

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**408**
**408 Request Timeout**

Video upscaling polling timeout (after 10 minutes).

```json
{
  "error": "Polling timeout"
}
```

### Model

**200 OK (Sync)**

Video upscaling completed. Returns upscaled video data with signed URLs.
Re-upscaling the same video returns `rawBytes` (base64 video data) instead of URLs.

```typescript
{
  jobId: string                              // Job identifier
  media: Array<{                             // Preferred — use this instead of operations
    name: string                             // Media identifier (raw UUID)
    projectId: string
    mediaMetadata: {
      mediaStatus: {
        mediaGenerationStatus: string        // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
        error?: { code: number; message: string }
      }
      visibility?: string
    }
    video?: {
      generatedVideo: {
        seed: number
        model: string                        // veo_3_1_upsampler_1080p | veo_3_1_upsampler_4k
        aspectRatio: string                  // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        isLooped: boolean
      }
      operation: { name: string }
    }
    mediaGenerationId: string                // Encoded reference ID for use in subsequent API calls
    videoUrl?: string                        // Signed video download URL (MP4, valid ~24h)
  }>
  operations: Array<{                        // Deprecated — will be removed in a future release
    operation?: {
      name: string
      metadata: {
        '@type': string
        name: string
        video: {
          seed: number
          mediaGenerationId: string          // Reference ID for the upscaled video
          prompt: string                     // Original video prompt
          fifeUrl: string                    // Signed video URL (MP4, valid ~24h)
          mediaVisibility: string
          servingBaseUri: string             // Signed thumbnail URL (JPEG, valid ~24h)
          model: string                      // veo_3_1_upsampler_1080p | veo_3_1_upsampler_4k
          isLooped: boolean
          aspectRatio: string                // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        }
      }
    }
    rawBytes?: string                        // Base64 video data (present when re-upscaling same video)
    sceneId: string
    mediaGenerationId: string
    status: string                           // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
  }>
  remainingCredits?: number
  captcha?: {                                // Captcha metadata
    service: string                          // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
    taskId?: string
    durationMs: number
    attempts: Array<{
      service: string
      taskId?: string
      durationMs: number
      success: boolean
      error?: string
    }>
  }
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.

```typescript
{
  jobid: string                              // Job identifier
  type: 'video'                              // Job type
  status: 'created'                          // Job status
  created: string                            // ISO 8601 timestamp
  request: {
    async: true
    mediaGenerationId: string                // Original video reference
    resolution?: string                      // "1080p" | "4K"
    replyUrl?: string
    replyRef?: string
  }
  response: {
    operations: Array<{
      operation: {
        name: string                         // Operation identifier
      }
      sceneId: string                        // Scene identifier
      status: 'MEDIA_GENERATION_STATUS_PENDING'
    }>
    captcha?: {                              // Present when captcha was used
      service: string                        // Provider or "UserProvided"
      taskId?: string                        // Absent for UserProvided
      durationMs: number
    }
  }
}
```

**Error**

Error response structure.

```typescript
{
  jobId?: string                             // Present for job-related errors
  error: string                              // Error summary message
  code?: number                              // HTTP status code
  response?: {                               // API response with error details
    error?: {
      code: number
      message: string
      status: string
      details?: Array<{
        '@type': string
        reason: string
      }>
    }
  }
}
```

### Examples

**Curl**
``` bash
# First generate a video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A serene mountain landscape at sunset"}' \
     "https://api.useapi.net/v1/google-flow/videos" > generate.json

# Extract mediaGenerationId from the response (prefer media[] over deprecated operations[])
MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json)

# Upscale the video to 1080p
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"resolution\": \"1080p\"}" \
     "https://api.useapi.net/v1/google-flow/videos/upscale" > upscale.json

# Extract upscaled video URL and download (prefer media[] over deprecated operations[])
VIDEO_URL=$(jq -r '.media[0].videoUrl' upscale.json)
curl "$VIDEO_URL" --output upscaled_video.mp4
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

// First generate a video
const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset'
  })
});

const generated = await generateResponse.json();
// Prefer media[] over deprecated operations[]
const mediaGenerationId = generated.media[0].mediaGenerationId;

// Upscale the video
const upscaleResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/upscale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mediaGenerationId,
    resolution: '1080p'
  })
});

const upscaled = await upscaleResponse.json();
// Prefer media[] over deprecated operations[]
const videoUrl = upscaled.media[0].videoUrl;

// Download upscaled video (Node.js)
const videoResponse = await fetch(videoUrl);
const videoBuffer = await videoResponse.arrayBuffer();
require('fs').writeFileSync('upscaled_video.mp4', Buffer.from(videoBuffer));
console.log('Upscaled video saved!');
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# First generate a video
generate_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos',
    headers=headers,
    json={'prompt': 'A serene mountain landscape at sunset'}
)
generated = generate_response.json()
# Prefer media[] over deprecated operations[]
media_generation_id = generated['media'][0]['mediaGenerationId']

# Upscale the video
upscale_response = requests.post(
    'https://api.useapi.net/v1/google-flow/videos/upscale',
    headers=headers,
    json={
        'mediaGenerationId': media_generation_id,
        'resolution': '1080p'
    }
)
upscaled = upscale_response.json()
# Prefer media[] over deprecated operations[]
video_url = upscaled['media'][0]['videoUrl']

# Download upscaled video
video_response = requests.get(video_url)
with open('upscaled_video.mp4', 'wb') as f:
    f.write(video_response.content)
print('Upscaled video saved!')
```

### Try It

<script>
  function displayUpscaledVideo(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    const mediaItems = response.media || [];
    const operations = response.operations || [];
    if (mediaItems.length === 0 && operations.length === 0) {
      mediaContainer.style.display = 'none';
      return;
    }

    const videos = [];
    if (mediaItems.length > 0) {
      mediaItems.forEach((item, index) => {
        videos.push({
          videoUrl: item.videoUrl,
          label: `Upscaled Video`
        });
      });
    } else {
      operations.forEach((op, index) => {
        if (op.rawBytes) {
          const dataUrl = `data:video/mp4;base64,${op.rawBytes}`;
          videos.push({
            videoUrl: dataUrl,
            label: `Download Upscaled Video (rawBytes)`,
            isRawBytes: true
          });
        }
        else if (op.operation?.metadata?.video) {
          const video = op.operation.metadata.video;
          videos.push({
            videoUrl: video.fifeUrl,
            label: `Upscaled Video`
          });
        }
      });
    }

    if (videos.length > 0) {
      const linksHTML = videos.map(vid => {
        if (vid.isRawBytes) {
          return `<a href="${vid.videoUrl}" download="upscaled_video.mp4" class="media-link video">${vid.label}</a>`;
        }
        return `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`;
      }).join(' ');

      mediaContainer.innerHTML = `<div class="media-links-container"><strong>Upscaled Video:</strong> ${linksHTML}</div>`;
      mediaContainer.style.display = 'block';
    } else {
      mediaContainer.style.display = 'none';
    }
  }

  async function apiExecutePostGoogleFlowVideosUpscale() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'captchaRetry') {
          payload[key] = parseInt(value);
        } else if (key === 'async') {
          payload[key] = value === 'true';
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/upscale', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayUpscaledVideo(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for video display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-mediaGenerationId"><span>mediaGenerationId<small> (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>)</small></span>
        <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:...">
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="1080p">1080p (default)</option>
          <option value="4K">4K (Ultra only)</option>
        </select>
      </label>
      <label for="input-async"><span>async<small> (fire-and-forget mode)</small></span>
        <select id="input-async" class="input-element input-query-param">
          <option value="false">false (default)</option>
          <option value="true">true</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
      <label for="input-captchaToken"><span>captchaToken<small> (optional, your own reCAPTCHA token)</small></span>
        <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token">
      </label>
      <label for="input-captchaRetry"><span>captchaRetry<small> (1-10, optional)</small></span>
        <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="3">
      </label>
      <label for="input-captchaOrder"><span>captchaOrder<small> (optional)</small></span>
        <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosUpscale()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos ===
Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos
## Generate Videos
<small>November 17, 2025 (May 18, 2026)</small>

---

Generate videos using Google Flow AI models ([Veo 3.1 Quality](https://deepmind.google/technologies/veo/), [Veo 3.1 Fast](https://deepmind.google/technologies/veo/), [Veo 3.1 Lite](https://deepmind.google/technologies/veo/), [Veo 3.1 Lite Lower Priority](https://deepmind.google/technologies/veo/)) from text prompts with optional start/end frames, reference images, or voice narration. Videos are returned as signed URLs ready for download.

This endpoint features dynamic concurrency management. Video generation typically completes within 60-180 seconds depending on the model and mode. The endpoint automatically polls for completion and returns the final result.

Use a [Google AI Ultra](https://one.google.com/ai) $125/m special subscription plan for `Veo 3.1 Fast` $5cents/video and `Veo 3.1 Quality` $50cents/video generations. `Veo 3.1 Lite Lower Priority` is available for Ultra subscribers with no credit cost but lower generation priority.

### Model Capabilities

| Parameter | [Veo 3.1 Quality](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-quality` | [Veo 3.1 Fast](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-fast` (default) | [Veo 3.1 Lite](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-lite` | [Veo 3.1 Lite Lower Priority](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-lite-low-priority` |
|-----------|:---:|:---:|:---:|:---:|
| T2V (text-to-video) | ✓ | ✓ | ✓ | ✓ |
| I2V (start frame) | ✓ | ✓ | ✓ | ✓ |
| I2V-FL (start + end) | ✓ | ✓ | ✓ | ✓ |
| R2V (reference images 1-3) | ✗ | ✓ | ✓ | ✓ |
| Voice narration | ✗ | ✓ | ✓ | ✓ |
| Aspect ratios | all | all | all | all |
| `duration` (sec) | 4, 6, 8 | 4, 6, 8 | 4, 6, 8 | 4, 6, 8 |
| `count` | ✓ (1-4) | ✓ (1-4) | ✓ (1-4) | ✓ (1-4) |
| `seed` | ✓ | ✓ | ✓ | ✓ |
| Subscription | all | all | all | Ultra only |
| Cost | 100 credits / $0.50 | 10 credits / $0.05 | 5 credits / $0.025 | free (lower priority) |

### Content Moderation

If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts — moderation decisions can vary between requests. Modifying the prompt, removing reference images, or swapping models can also help, as each has different content-moderation behavior.

### Response Codes

#### 429 — Rate limit / quota exhausted

Google returns at least four known distinct `RESOURCE_EXHAUSTED` variants in the response body. Always check the **reason** field on the returned error to pick the right strategy:

| Reason code | What it means | What to do |
|---|---|---|
| `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | **This is a captcha-provider issue, not a useapi.net issue.** Google's reCAPTCHA Enterprise scored the captcha token below its risk threshold — usually because the provider is overloaded or being fingerprinted by Google (the provider's infrastructure is processing too many high-volume requests at once and Google flags them collectively). Our worker has already auto-retried with fresh captcha tokens (up to `captchaRetry` attempts, default 3) before returning this. | **Spread the load across multiple captcha providers** — configure several providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) (e.g. CapSolver + AntiCaptcha + 2Captcha) and use `captchaOrder` on the request to cycle through them. Adding balance to existing providers can also help, since some prioritize higher-balance accounts. As a short-term measure, wait 30-60s and retry, or bump `captchaRetry` higher in the request body. |
| `PUBLIC_ERROR_USER_REQUESTS_THROTTLED` | Google-side per-user concurrency limit. The token was fine; this account is sending too many requests at once. | **Hold for ~hour**, retry after 10-60min. Reduce parallel generations per account. |
| `PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED` | This account hit Google's per-model daily quota. Retrying within the day will not succeed. | **Hold for the day** (quota resets at UTC midnight), or switch to a different model. |
| `PUBLIC_ERROR_USER_QUOTA_REACHED` | This account hit its overall Google Flow quota cap — separate from per-model limits, blocks **all** models on this account. | **Add more Google Flow accounts** via [POST /accounts/`email`](/docs/api-google-flow-v1/post-google-flow-accounts-email) so the load is spread. Hold this specific account until the quota resets, or omit `email` in your request to let load balancing pick a healthier account. |

**Automatic quarantine.** When you omit `email`, the load balancer automatically quarantines an account on any of `PUBLIC_ERROR_USER_QUOTA_REACHED`, `PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED`, or `PUBLIC_ERROR_USER_REQUESTS_THROTTLED` and routes subsequent requests to the remaining healthy accounts. See [Quarantine pre-filter](/docs/api-google-flow-v1/get-google-flow-jobs#step-1--quarantine-pre-filter) for the TTLs and exact behavior.

If every account is quarantined for the requested model, the response is `429` with `error: "no_eligible_account"` plus a `Retry-After` header — see the example payload in the 429 response tab below.

#### 503 — Service unavailable

Transient Google-side issue. Wait 5-10 seconds and retry. If the response body says `"Captcha service failed"`, the issue is with your captcha provider (check API key and balance) rather than Google — don't retry until the provider is back.

#### 403 — Request rejected by Google

Captcha token rejected by Google despite our internal retries — a captcha-provider issue. Increase `captchaRetry` (default 3) in the request body to 5 or higher, and configure additional providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) so `captchaOrder` can cycle across them. If issues persist, contact your reCAPTCHA provider(s) support.
> **https://api.useapi.net/v1/google-flow/videos**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
  "model": "veo-3.1-fast",
  "aspectRatio": "landscape",
  "duration": 8,
  "count": 2,
  "seed": 123456
}
```

- `email` is optional. The email address of the Google Flow account to use.

  When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **video generation** job statistics to select the healthiest account.

  If reference images (`startImage`, `endImage`, or `referenceImage_1` to `_3`) are provided, the `email` parameter can be omitted—the API will automatically use the same account where the images were uploaded.
- `prompt` is **required**, text description for video generation.
- `model` is optional, the AI model to use for video generation (default: `veo-3.1-fast`).  
  Supported values: `veo-3.1-quality`, `veo-3.1-fast`, `veo-3.1-lite` (faster, lower cost), `veo-3.1-lite-low-priority` (Ultra only, no credits, lower priority).
- `aspectRatio` is optional, output video aspect ratio (default: `landscape`).  
  Supported values: `landscape` and `portrait`.
- `duration` is optional, output video length in seconds (default: `8`).  
  Supported values: `4`, `6`, `8`. **`4` and `6` require an Ultra subscription** and apply only to T2V, I2V, and I2V-FL modes — they are **not supported with `referenceImage_*` (R2V/Ingredients) or with [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend)**, both of which only support `8`. Generation time is the same regardless of duration; only output length changes.
- `count` is optional, number of video variations to generate (1-4, default: `1`).
- `seed` is optional, random seed for reproducible results (integer ≥ 0).
- `startImage` is optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for I2V mode (video starts with this frame).
- `endImage` is optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for I2V-FL mode (video ends with this frame, requires `startImage`).
- `referenceImage_1` to `referenceImage_3` are optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for R2V mode (1-3 reference images for style/composition). Supported by `veo-3.1-fast`, `veo-3.1-lite`, and `veo-3.1-lite-low-priority` (not `veo-3.1-quality`).
- `voice` is optional, voice name for AI narration in the generated video (case-insensitive). Requires at least one `referenceImage` (R2V mode). Preview voice samples using the dropdown in Try It below.
```json
["achird","achernar","algieba","algenib","alnilam","aoede","autonoe","callirrhoe","charon","despina","enceladus","erinome","fenrir","gacrux","iapetus","kore","laomedeia","leda","orus","puck","pulcherrima","rasalgethi","sadachbia","sadaltager","schedar","sulafat","umbriel","vindemiatrix","zephyr","zubenelgenubi"]
```
Voice samples: <code>https://www.gstatic.com/aistudio/voices/samples/{Name}.wav</code>

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status. Useful for avoiding long request timeouts since video generation takes 60-180 seconds.
- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.
- `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

**Important:**
- Cannot use both reference images (R2V) and start/end frames (I2V) in the same request
- End frame only (without start frame) is not supported
- R2V mode works with `veo-3.1-fast`, `veo-3.1-lite`, and `veo-3.1-lite-low-priority` (not `veo-3.1-quality`)
- Voice narration requires at least one `referenceImage` (R2V mode)
- `duration: 4` and `duration: 6` require an Ultra subscription and apply only to T2V/I2V/I2V-FL — not R2V or video extensions, both of which only support `duration: 8`

### Responses

**200**
**200 OK**

Videos generated successfully. Returns job ID, media array with video data, and operations array (deprecated) with video URLs and metadata.

```json
{
  "jobId": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow",
  "media": [
    {
      "name": "CAUSJ...redacted...OWQ5ZA",
      "projectId": "...redacted...",
      "mediaMetadata": {
        "mediaStatus": {
          "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
        },
        "visibility": "PRIVATE"
      },
      "video": {
        "generatedVideo": {
          "seed": 123456,
          "model": "veo_3_1_t2v",
          "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
          "isLooped": false,
          "prompt": "A serene mountain landscape at sunset with camera slowly panning right"
        },
        "operation": {
          "name": "d00af...redacted...6f7a"
        }
      },
      "mediaGenerationId": "user:12345-email:6a6f...-video:CAUSJ...redacted",
      "videoUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted..."
    }
  ],
  "operations": [
    {
      "operation": {
        "name": "d00af...redacted...6f7a",
        "metadata": {
          "@type": "type.googleapis.com/google.internal.labs.aisandbox.v1.Media",
          "name": "CAUSJ...redacted...OWQ5ZA",
          "video": {
            "seed": 123456,
            "mediaGenerationId": "CAUSJ...redacted...OWQ5ZA",
            "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
            "fifeUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...redacted...",
            "mediaVisibility": "PRIVATE",
            "servingBaseUri": "https://storage.googleapis.com/ai-sandbox-videofx/image/...redacted...",
            "model": "veo_3_1_t2v",
            "isLooped": false,
            "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
          }
        }
      },
      "sceneId": "323c0...redacted...3ebf6",
      "mediaGenerationId": "CAUSJ...redacted...OWQ5ZA",
      "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
    }
  ],
  "remainingCredits": 18760,
  "captcha": {
    "service": "AntiCaptcha",
    "taskId": "abc123...",
    "durationMs": 3500,
    "attempts": [
      {
        "service": "AntiCaptcha",
        "taskId": "abc123...",
        "durationMs": 3500,
        "success": true
      }
    ]
  }
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Video generation is processing in the background.

Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status.

```json
{
  "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow",
  "type": "video",
  "status": "created",
  "created": "2025-11-17T12:34:56.789Z",
  "request": {
    "async": true,
    "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
    "email": "jo***@gmail.com",
    "model": "veo-3.1-fast",
    "aspectRatio": "landscape",
    "duration": 8,
    "count": 2,
    "seed": 123456,
    "replyUrl": "https://your-domain.com/webhook",
    "replyRef": "custom-reference-123"
  },
  "response": {
    "operations": [
      {
        "operation": {
          "name": "1450903d...redacted...9c86f0"
        },
        "sceneId": "1450903d...redacted...9c86f0",
        "status": "MEDIA_GENERATION_STATUS_PENDING"
      },
      {
        "operation": {
          "name": "f2eec9bd...redacted...e16f7a"
        },
        "sceneId": "f2eec9bd...redacted...e16f7a",
        "status": "MEDIA_GENERATION_STATUS_PENDING"
      }
    ],
    "captcha": {
      "service": "AntiCaptcha",
      "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
      "durationMs": 5357
    }
  }
}
```

**400**
**400 Bad Request**

Invalid request (validation error, mode conflict, email mismatch, or content policy violation).

**Validation error:**
```json
{
  "error": "Model 'veo-3.1-quality' does not support R2V mode (MULTI_REFERENCE_NO_STYLE)"
}
```

**Content policy error:**
```json
{
  "jobId": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow",
  "error": "API error: 400",
  "code": 400,
  "response": {
    "error": {
      "code": 400,
      "message": "Request contains an invalid argument.",
      "status": "INVALID_ARGUMENT",
      "details": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "reason": "PUBLIC_ERROR_UNSAFE_GENERATION"
        }
      ]
    }
  }
}
```

**Content policy error (direct):**
```json
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_UNSAFE_GENERATION"
      }
    ]
  }
}
```

**All operations failed (during polling):**
```json
{
  "jobId": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow",
  "error": "All operations failed",
  "code": 400,
  "response": {
    "operations": [
      {
        "operation": {
          "name": "a789f1...redacted",
          "error": {
            "code": 3,
            "message": "PUBLIC_ERROR_MINOR"
          }
        },
        "sceneId": "a629a9...redacted",
        "status": "MEDIA_GENERATION_STATUS_FAILED"
      }
    ]
  }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**403**
**403 Forbidden**

Request rejected by Google. See [Response Codes › 403](#403--request-rejected-by-google) above for guidance. Example payload:

```json
{
  "code": 403,
  "created": "2025-12-23T21:54:26.393Z",
  "error": "API error: 403",
  "jobid": "j1223215426393445325v-u12345-email:us***@gmail.com-bot:google-flow",
  "request": {
    "aspectRatio": "landscape",
    "count": 1,
    "duration": 8,
    "email": "us***@gmail.com",
    "model": "veo-3.1-fast",
    "prompt": "A cinematic shot of a sunset over the ocean..."
  },
  "response": {
    "captcha": {
      "attempts": [
        {
          "service": "AntiCaptcha",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "success": true
        },
        {
          "service": "AntiCaptcha",
          "taskId": "fd044078-0a4a-4303-a585-26fd5d2acb00",
          "durationMs": 5376,
          "success": true
        },
        {
          "service": "AntiCaptcha",
          "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42",
          "durationMs": 5789,
          "success": true
        }
      ],
      "durationMs": 18091,
      "service": "AntiCaptcha",
      "taskId": "ab0251dc-6930-4a82-966a-71fe6ab6aa42"
    },
    "error": {
      "code": 403,
      "details": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "reason": "PUBLIC_ERROR_SOMETHING_WENT_WRONG"
        }
      ],
      "message": "reCAPTCHA evaluation failed",
      "status": "PERMISSION_DENIED"
    }
  },
  "status": "failed",
  "type": "video",
  "updated": "2025-12-23T21:54:45.319Z"
}
```

**404**
**404 Not Found**

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

**408**
**408 Request Timeout**

Video generation polling timeout (after 10 minutes).

```json
{
  "error": "Video generation polling timeout after 120 attempts (600s)"
}
```

**429**
**429 Too Many Requests**

Google returns at least four known distinct `RESOURCE_EXHAUSTED` variants. See [Response Codes › 429](#429--rate-limit--quota-exhausted) above for the right strategy per reason. Example payloads:

**Example — reCAPTCHA evaluation failed (`PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC`):**
```json
{
  "error": {
    "code": 429,
    "message": "reCAPTCHA evaluation failed",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC"
      }
    ]
  }
}
```

**Example — per-user throttling:**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_REQUESTS_THROTTLED"
      }
    ]
  }
}
```

**Example — per-model daily quota reached:**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED",
        "metadata": {
          "canUpgradeForQuota": "true"
        }
      }
    ]
  }
}
```

**Example — account-wide quota reached (`PUBLIC_ERROR_USER_QUOTA_REACHED`):**
```json
{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_QUOTA_REACHED"
      }
    ]
  }
}
```

**Example — every configured account is quarantined for the requested model (`no_eligible_account`):**

When you omit `email` and **every** one of your accounts is currently quarantined for the requested model (see [Quarantine pre-filter](/docs/api-google-flow-v1/get-google-flow-jobs#step-1--quarantine-pre-filter)), the API short-circuits with this `429` response — no upstream call to Google is made. Response headers include `Retry-After: <seconds>` per [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3).

```json
{
  "error": "no_eligible_account",
  "message": "All your Google Flow accounts have hit Google's daily per-user quota. Quota resets at UTC midnight (2026-05-20T00:00:10.000Z).",
  "retryAfter": "2026-05-20T00:00:10.000Z",
  "skipReasons": [
    { "email": "alice@gmail.com", "reason": "PUBLIC_ERROR_USER_QUOTA_REACHED", "model": "*" },
    { "email": "bob@gmail.com",   "reason": "PUBLIC_ERROR_USER_QUOTA_REACHED", "model": "*" }
  ]
}
```

`skipReasons` lists every account considered and the reason it was filtered, so you can decide whether to wait, switch model, or add more accounts. To bypass the load balancer entirely, specify `email` explicitly — the request will be sent to Google regardless of quarantine state.

**503**
**503 Service Unavailable**

Service temporarily unavailable or captcha provider error. See [Response Codes › 503](#503--service-unavailable) above for guidance. Example payloads:

```json
{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable.",
    "status": "UNAVAILABLE"
  }
}
```

```json
{
  "error": "Captcha service failed: ERROR_ZERO_BALANCE",
  "code": 503
}
```

**596**
**596 Session Error**

Google session refresh failed. The account needs to be reconfigured. Delete the account using [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by strictly following the procedure in [Setup Google Flow](/docs/start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session: 500 Internal Server Error"
}
```

### Model

**200 OK (Sync)**

Video generation completed. Returns full video data with signed URLs.

```typescript
{
  jobId: string                              // Job identifier
  media: Array<{                             // Preferred — use this instead of operations
    name: string                             // Media identifier (raw UUID)
    projectId: string
    mediaMetadata: {
      mediaStatus: {
        mediaGenerationStatus: string        // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
        error?: { code: number; message: string }
      }
      visibility?: string                    // "PRIVATE"
      requestData?: object                   // Original request data
    }
    video?: {
      generatedVideo: {
        seed: number
        model: string                        // veo_3_1_t2v | veo_3_1_i2v | veo_3_1_i2v_fl | veo_3_1_r2v
        aspectRatio: string                  // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        isLooped: boolean
        prompt?: string
      }
      operation: { name: string }
    }
    mediaGenerationId: string                // Encoded reference ID for use in subsequent API calls
    videoUrl?: string                        // Signed video download URL (MP4, valid ~24h)
  }>
  operations: Array<{                        // Deprecated — will be removed in a future release
    operation: {
      name: string
      metadata: {
        '@type': string
        name: string
        video: {
          seed: number
          mediaGenerationId: string
          prompt: string
          fifeUrl: string                    // Signed video URL (MP4, valid ~24h)
          mediaVisibility: string
          servingBaseUri: string             // Signed thumbnail URL (JPEG, valid ~24h)
          model: string                      // veo_3_1_t2v | veo_3_1_i2v | veo_3_1_i2v_fl | veo_3_1_r2v
          isLooped: boolean
          aspectRatio: string                // VIDEO_ASPECT_RATIO_LANDSCAPE | PORTRAIT
        }
      }
    }
    sceneId: string
    mediaGenerationId: string
    status: string                           // MEDIA_GENERATION_STATUS_SUCCESSFUL | FAILED
  }>
  remainingCredits?: number
  captcha?: {                                // Captcha metadata
    service: string                          // "CapSolver" | "AntiCaptcha" | "YesCaptcha" | "CapMonster" | "SolveCaptcha" | "2Captcha" | "EzCaptcha" | "UserProvided"
    taskId?: string
    durationMs: number
    attempts: Array<{
      service: string
      taskId?: string
      durationMs: number
      success: boolean
      error?: string
    }>
  }
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response.

```typescript
{
  jobid: string                              // Job identifier
  type: 'video'                              // Job type
  status: 'created'                          // Job status
  created: string                            // ISO 8601 timestamp
  request: {
    async: true
    prompt: string
    email?: string
    model?: string
    aspectRatio?: string
    count?: number
    seed?: number
    startImage?: string
    endImage?: string
    referenceImage_1?: string
    referenceImage_2?: string
    referenceImage_3?: string
    replyUrl?: string
    replyRef?: string
  }
  response: {
    operations: Array<{
      operation: {
        name: string                         // Operation identifier
      }
      sceneId: string                        // Scene identifier
      status: 'MEDIA_GENERATION_STATUS_PENDING'
    }>
    captcha?: {                              // Present when captcha was used
      service: string                        // Provider that generated final token or "UserProvided"
      taskId?: string                        // Task ID from provider (absent for UserProvided)
      durationMs: number                     // Total captcha solving time
      attempts?: Array<{                     // All captcha attempts (if retries occurred)
        service: string
        taskId?: string
        durationMs: number
        success: boolean
      }>
    }
  }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
  jobId?: string                             // Present for job-related errors
  error: string                              // Error summary message
  code?: number                              // HTTP status code
  response?: {                               // API response with error details
    operations?: Array<{                     // Present when operations failed
      operation: {
        name: string
        error?: { code: number; message: string }
      }
      sceneId: string
      status: string
    }>
    error?: {                                // Present for direct API errors
      code: number
      message: string
      status: string
      details?: Array<{
        '@type': string
        reason: string
      }>
    }
  }
  // The following siblings appear only on the load-balancer empty-set 429,
  // i.e. when error === "no_eligible_account" (see 429 response tab).
  message?: string                           // Customer-facing explanation
  retryAfter?: string                        // ISO-8601 timestamp of earliest retry
  skipReasons?: Array<{                      // Per-account filter rationale
    email: string
    reason: string                           // Google 429 reason that triggered the quarantine
    model: string                            // Quarantined model, or "*" for account-wide
  }>
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
       "model": "veo-3.1-fast",
       "aspectRatio": "landscape",
       "duration": 8,
       "count": 2,
       "seed": 123456
     }' \
     "https://api.useapi.net/v1/google-flow/videos" > response.json

# Extract video URLs using jq (prefer media[] over deprecated operations[])
cat response.json | jq -r '.media[0].videoUrl'
cat response.json | jq -r '.media[1].videoUrl'

# Download videos using curl
curl "$(cat response.json | jq -r '.media[0].videoUrl')" --output video_1.mp4
curl "$(cat response.json | jq -r '.media[1].videoUrl')" --output video_2.mp4
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const apiUrl = 'https://api.useapi.net/v1/google-flow/videos';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset with camera slowly panning right',
    model: 'veo-3.1-fast',
    aspectRatio: 'landscape',
    duration: 8,
    count: 2,
    seed: 123456
  })
});

const result = await response.json();
console.log('Generated videos:', result.media.length);

// Download videos (prefer media[] over deprecated operations[])
for (const [index, item] of result.media.entries()) {
  console.log(`Video ${index + 1} seed:`, item.video?.generatedVideo?.seed);
  console.log(`mediaGenerationId:`, item.mediaGenerationId);
  console.log(`Video URL:`, item.videoUrl);

  // Download video (Node.js)
  const videoResponse = await fetch(item.videoUrl);
  const videoBuffer = await videoResponse.arrayBuffer();
  const fs = require('fs');
  fs.writeFileSync(`generated_video_${index + 1}.mp4`, Buffer.from(videoBuffer));
}
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
api_url = 'https://api.useapi.net/v1/google-flow/videos'

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

data = {
    'prompt': 'A serene mountain landscape at sunset with camera slowly panning right',
    'model': 'veo-3.1-fast',
    'aspectRatio': 'landscape',
    'duration': 8,
    'count': 2,
    'seed': 123456
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()

print(f"Generated {len(result['media'])} videos")

# Download videos (prefer media[] over deprecated operations[])
for index, item in enumerate(result['media']):
    video = item.get('video', {}).get('generatedVideo', {})
    print(f"Video {index + 1} seed:", video.get('seed'))
    print(f"mediaGenerationId:", item.get('mediaGenerationId'))

    # Download video
    video_response = requests.get(item['videoUrl'])
    with open(f'generated_video_{index + 1}.mp4', 'wb') as f:
        f.write(video_response.content)
```

### Try It

<script>
  function displayGoogleFlowVideos(response, elementId) {
    const mediaContainer = document.getElementById(`${elementId}-media-links`);
    if (!mediaContainer) return;

    mediaContainer.innerHTML = '';

    const mediaItems = response.media || [];
    if (mediaItems.length === 0 && (!response.operations || response.operations.length === 0)) {
      mediaContainer.style.display = 'none';
      return;
    }

    const videos = [];
    if (mediaItems.length > 0) {
      mediaItems.forEach((item, index) => {
        const seed = item.video?.generatedVideo?.seed;
        videos.push({
          videoUrl: item.videoUrl,
          seed: seed,
          label: `Video ${videos.length + 1}${seed ? ` (seed: ${seed})` : ''}`
        });
      });
    } else {
      response.operations.forEach((op, index) => {
        if (op.operation?.metadata?.video) {
          const video = op.operation.metadata.video;
          videos.push({
            videoUrl: video.fifeUrl,
            seed: video.seed,
            label: `Video ${videos.length + 1}${video.seed ? ` (seed: ${video.seed})` : ''}`
          });
        }
      });
    }

    if (videos.length > 0) {
      const linksHTML = videos.map(vid =>
        `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`
      ).join(' ');

      mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Videos:</strong> ${linksHTML}</div>`;
      mediaContainer.style.display = 'block';
    } else {
      mediaContainer.style.display = 'none';
    }
  }

  async function apiExecutePostGoogleFlowVideos() {
    const tokenElement = document.getElementById('input-token');
    const elementId = 'input';

    const payload = {};

    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value !== '' && value !== undefined) {
        const key = id.replace('input-', '');
        if (key === 'seed' || key === 'count' || key === 'captchaRetry') {
          payload[key] = parseInt(value);
        } else if (key === 'async') {
          payload[key] = value === 'true';
        } else {
          payload[key] = value;
        }
      }
    });

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    };

    const mediaLinks = document.getElementById(`${elementId}-media-links`);
    if (mediaLinks) mediaLinks.style.display = 'none';

    const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos', elementId, data, { includeTimer: true });

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayGoogleFlowVideos(response, elementId);
      } catch (e) {
        console.error('Failed to parse response for video display:', e);
      }
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-email"><span>email<small> (optional)</small></span>
        <input id="input-email" type="text" class="input-element input-query-param" placeholder="john@gmail.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="A serene mountain landscape">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="veo-3.1-fast">veo-3.1-fast (default)</option>
          <option value="veo-3.1-quality">veo-3.1-quality</option>
          <option value="veo-3.1-lite">veo-3.1-lite (faster, lower cost)</option>
          <option value="veo-3.1-lite-low-priority">veo-3.1-lite-low-priority (Ultra only, no credits, lower priority)</option>
        </select>
      </label>
      <label for="input-aspectRatio"><span>aspectRatio</span>
        <select id="input-aspectRatio" class="input-element input-query-param">
          <option value="landscape">landscape (default)</option>
          <option value="portrait">portrait</option>
        </select>
      </label>
      <label for="input-duration"><span>duration<small> (sec, Ultra-only for 4 and 6, T2V/I2V/I2V-FL only)</small></span>
        <select id="input-duration" class="input-element input-query-param">
          <option value="">8 (default)</option>
          <option value="4">4</option>
          <option value="6">6</option>
          <option value="8">8</option>
        </select>
      </label>
      <label for="input-count"><span>count</span>
        <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="1">
      </label>
      <label for="input-seed"><span>seed</span>
        <input id="input-seed" type="number" class="input-element input-query-param" min="0" placeholder="(random)">
      </label>
      <label for="input-async"><span>async<small> (fire-and-forget mode, see <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/jobId</a>)</small></span>
        <select id="input-async" class="input-element input-query-param">
          <option value="false">false (default)</option>
          <option value="true">true</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (custom reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123">
      </label>
      <label for="input-startImage"><span>startImage<small> (optional, from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a>)</small></span>
        <input id="input-startImage" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-endImage"><span>endImage<small> (optional, requires startImage)</small></span>
        <input id="input-endImage" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-referenceImage_1"><span>referenceImage_1<small> (optional, R2V mode)</small></span>
        <input id="input-referenceImage_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-referenceImage_2"><span>referenceImage_2</span>
        <input id="input-referenceImage_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-referenceImage_3"><span>referenceImage_3</span>
        <input id="input-referenceImage_3" type="text" class="input-element input-query-param" placeholder="user:123-email:...">
      </label>
      <label for="input-voice"><span>voice<small> (optional, requires referenceImage, select to preview)</small></span>
        <div>
          <select id="input-voice" class="input-element input-query-param" onchange="
            var audio = document.getElementById('voice-preview');
            var val = this.value;
            if (val) {
              audio.src = 'https://www.gstatic.com/aistudio/voices/samples/' + val.charAt(0).toUpperCase() + val.slice(1) + '.wav';
              audio.style.display = 'block';
              audio.play();
            } else {
              audio.pause();
              audio.style.display = 'none';
            }
          ">
            <option value="">none</option>
            <option value="achird">Achird</option>
            <option value="achernar">Achernar</option>
            <option value="algieba">Algieba</option>
            <option value="algenib">Algenib</option>
            <option value="alnilam">Alnilam</option>
            <option value="aoede">Aoede</option>
            <option value="autonoe">Autonoe</option>
            <option value="callirrhoe">Callirrhoe</option>
            <option value="charon">Charon</option>
            <option value="despina">Despina</option>
            <option value="enceladus">Enceladus</option>
            <option value="erinome">Erinome</option>
            <option value="fenrir">Fenrir</option>
            <option value="gacrux">Gacrux</option>
            <option value="iapetus">Iapetus</option>
            <option value="kore">Kore</option>
            <option value="laomedeia">Laomedeia</option>
            <option value="leda">Leda</option>
            <option value="orus">Orus</option>
            <option value="puck">Puck</option>
            <option value="pulcherrima">Pulcherrima</option>
            <option value="rasalgethi">Rasalgethi</option>
            <option value="sadachbia">Sadachbia</option>
            <option value="sadaltager">Sadaltager</option>
            <option value="schedar">Schedar</option>
            <option value="sulafat">Sulafat</option>
            <option value="umbriel">Umbriel</option>
            <option value="vindemiatrix">Vindemiatrix</option>
            <option value="zephyr">Zephyr</option>
            <option value="zubenelgenubi">Zubenelgenubi</option>
          </select>
          <audio id="voice-preview" style="display:none;width:100%;margin-top:4px" controls></audio>
        </div>
      </label>
      <label for="input-captchaToken"><span>captchaToken<small> (optional, your own reCAPTCHA token)</small></span>
        <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token">
      </label>
      <label for="input-captchaRetry"><span>captchaRetry<small> (1-10, optional)</small></span>
        <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="3">
      </label>
      <label for="input-captchaOrder"><span>captchaOrder<small> (optional)</small></span>
        <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideos()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/start-here/setup-kling ===
Document URL: https://useapi.net/docs/start-here/setup-kling
# <img style="height:1em;vertical-align: middle;" src="/assets/images/kling.svg"> Setup Kling 
<small>April 18, 2025 (April 2, 2026)</small>

## Table of contents
<small>Approximately 2 minutes to complete setup steps.</small>  

---
> This is the setup guide for [Kling API](/docs/api-kling-v1). An active [Kling AI](https://kling.ai/app/) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work.

## Create Kling AI account

Navigate to [https://kling.ai/app/](https://kling.ai/app) and sign up with an email account. Our API does not support Gmail or Apple accounts. We strongly recommend creating a separate Kling AI account designated for API work.

![](/assets/images/kling_setup_1.png)

![](/assets/images/kling_setup_2.png)

![](/assets/images/kling_setup_3.png)

![](/assets/images/kling_setup_4.png)

## Verify and add account

Use the form below to verify your credentials and add your Kling account.

Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-kling-v1/post-kling-accounts) directly.

<script>
  async function apiTestAccountKling(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-Kling-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let email = document.getElementById(`post-accounts-Kling-email`)?.value;
      let password = document.getElementById(`post-accounts-Kling-password`)?.value;

      email = email && email.length ? email : undefined;
      password = password && password.length ? password : undefined;

      const body = { password, email, maxJobs: 10 };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/kling/accounts`, 'post-accounts-Kling', data);
  }
</script>

<form id="post-accounts-Kling" onsubmit="apiTestAccountKling(document.getElementById('post-accounts-Kling-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Kling-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Kling-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Kling-email"><span>email&nbsp;&nbsp;&nbsp;</span>
        <input id="post-accounts-Kling-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Kling-password"><span>password</span>
        <input id="post-accounts-Kling-password" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Kling-action"><span>action</span>
        <select id="post-accounts-Kling-action" class="input-element">
          <option value="verify">Verify — test credentials only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Kling-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-Kling-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-kling-v1 ===
Document URL: https://useapi.net/docs/api-kling-v1

# <img style="height:1em;vertical-align: middle;" src="/assets/images/kling.svg"> Kling API v1 

<small>April 18, 2025 (May 6, 2026)</small>

This is an [experimental](/docs/legal) API for [Kling AI](https://kling.ai/app), a generative artificial intelligence service developed by Chinese short video giant [Kuaishou Technology](https://www.kuaishou.com/en).

Kling AI is considered by many to be the [best AI model](https://artificialanalysis.ai/text-to-video/arena?tab=leaderboard&input=image), leading the pack with prompt adherence, video quality and unmatched consistency.

Our API support Kling models `v3`, `O1`, `2.6`, `2.5`, `2.1`, `2.0`, `1.6` and `1.5` with optional audio generation for enhanced video experiences. Model `v3` brings enhanced video quality with 3-15s duration, multi-shot storytelling, VIDEO elements, improved image generation with 4k resolution, and custom voice support. Model `2.6` supports Native Audio generation. [Motion Control](/blog/260106) (apply motion from video to image) supports v3.0 and v2.6 models.

[Avatars 2.0](/docs/api-kling-v1/get-kling-avatars) with AI-powered lip-sync video generation and TTS support. [Elements](/docs/api-kling-v1/get-kling-elements) for creating reusable character/object references across v3 and O1 generations. 

In contrast to the [official](https://klingai.com/global/dev/pricing) Kling API, which starts at $4,200/month Video Generation ($2,100/month Image Generation) and requires a 3-month subscription commitment, you can start using the API with a Free or [$10/month](https://kling.ai/app/membership/membership-plan) Standard plan and upgrade or [top up](https://kling.ai/app/membership/spirit-unit) your account as needed.

As a bonus, you can execute unlimited generations of:
* Speech generation (up to **5 minutes** long) via [POST tts/create](/docs/api-kling-v1/post-kling-tts-create)  
* Face detection via [POST images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces)  
These features are available for all Kling subscription plans, including the **free** one.  

<details markdown="block">

<summary><small><b>💲 Cost calculator</b></small></summary>
  <a href="https://kling.ai/app/membership/membership-plan">Current Kling prices and offers</a>
  <div class="input-field">
    <div class="input-field-row">
      <label for="planSelect"><h4>Select Subscription Plan</h4></label>
      <select id="planSelect" class="input-element">
        <option value="std_monthly">Standard monthly - $9/m for 660 credits ($0.01364 per credit)</option>
        <option value="pro_monthly" selected>Pro monthly - $33/m for 3000 credits ($0.01100 per credit)</option>
        <option value="premier_monthly">Premier monthly - $81/m for 8000 credits ($0.01012 per credit)</option>
        <option value="ultra_monthly">Ultra monthly - $160/m for 26000 credits ($0.00615 per credit)</option>
        <option value="std_yearly">Standard yearly - $79/y for 7920 credits ($0.00998 per credit)</option>
        <option value="pro_yearly">Pro yearly - $293/y for 36000 credits ($0.00814 per credit)</option>
        <option value="premier_yearly">Premier yearly - $729/y for 96000 credits ($0.00759 per credit)</option>
        <option value="ultra_yearly">Ultra yearly - $1430/y for 312000 credits ($0.00458 per credit)</option>
        <option value="credits">16000 credits card - $200 for 16000 credits ($0.01250 per credit)</option>
        <option value="custom">Custom...</option>    </select>
    </div>
  </div>
  
  <div id="customInputs" style="display: none;">
    <div class="input-field">
      <div class="input-field-row">
        <label for="customCost">Custom Cost ($):</label>
        <input type="number" id="customCost" class="input-element" value="160">
      </div>
    </div>
    <div class="input-field">
      <div class="input-field-row">
        <label for="customCredits">Custom Credits:</label>
        <input type="number" id="customCredits" class="input-element" value="26000">
      </div>
    </div>
  </div>
  
  <div>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Cost $</th>
          <th>Credits</th>
          <th>Single credit cost</th>
        </tr>
      </thead>
      <tbody>
        <tr id="planDetails">
          <td id="planName">Pro monthly (3000 credits per month)</td>
          <td id="planCost">$33</td>
          <td id="planCredits">3000</td>
          <td id="creditCost">$0.01100</td>
        </tr>
      </tbody>
    </table>
  </div>

  <h4>Generation Pricing</h4>
  <div>
    <table>
      <thead>
        <tr>
          <th>Kling Model</th>
          <th>Credits</th>
          <th>Single generation cost</th>
        </tr>
      </thead>
      <tbody id="generationTableBody">
        <tr>
          <td>2.6 Pro Native Audio 1080p 10sec</td>
          <td>70</td>
          <td class="gen-price">$0.77</td>
        </tr>
        <tr>
          <td>2.6 Pro Native Audio 1080p 5sec</td>
          <td>35</td>
          <td class="gen-price">$0.39</td>
        </tr>
        <tr>
          <td>2.6 Pro 1080p 10sec</td>
          <td>50</td>
          <td class="gen-price">$0.55</td>
        </tr>
        <tr>
          <td>2.6 Pro 1080p 5sec</td>
          <td>25</td>
          <td class="gen-price">$0.28</td>
        </tr>
        <tr>
          <td>2.6 Std 720p 10sec</td>
          <td>30</td>
          <td class="gen-price">$0.33</td>
        </tr>
        <tr>
          <td>2.6 Std 720p 5sec</td>
          <td>15</td>
          <td class="gen-price">$0.17</td>
        </tr>
        <tr>
          <td>2.5 Pro 1080p 10sec</td>
          <td>50</td>
          <td class="gen-price">$0.68</td>
        </tr>
        <tr>
          <td>2.5 Pro 1080p 5sec</td>
          <td>25</td>
          <td class="gen-price">$0.34</td>
        </tr>
        <tr>
          <td>2.1 Pro 1080p 10sec</td>
          <td>70</td>
          <td class="gen-price">$0.53</td>
        </tr>
        <tr>
          <td>2.1 Pro 1080p 5sec</td>
          <td>35</td>
          <td class="gen-price">$0.27</td>
        </tr>
        <tr>
          <td>2.1 Std 720p 10sec</td>
          <td>40</td>
          <td class="gen-price">$0.30</td>
        </tr>
        <tr>
          <td>2.1 Std 720p 5sec</td>
          <td>20</td>
          <td class="gen-price">$0.15</td>
        </tr>
        <tr>
          <td>2.x Master 1080p 10sec</td>
          <td>200</td>
          <td class="gen-price">$1.52</td>
        </tr>
        <tr>
          <td>2.x Master 1080p 5sec</td>
          <td>100</td>
          <td class="gen-price">$0.76</td>
        </tr>
        <tr>
          <td>1.6 Pro 1080p 10sec</td>
          <td>70</td>
          <td class="gen-price">$0.53</td>
        </tr>
        <tr>
          <td>1.6 Pro 1080p 5sec</td>
          <td>35</td>
          <td class="gen-price">$0.27</td>
        </tr>
        <tr>
          <td>1.6 Std 720p 10sec</td>
          <td>40</td>
          <td class="gen-price">$0.30</td>
        </tr>
        <tr>
          <td>1.6 Std 720p 5sec</td>
          <td>20</td>
          <td class="gen-price">$0.15</td>
        </tr>
        <tr>
          <td>v3 Motion Pro (per sec)</td>
          <td>12</td>
          <td class="gen-price">$0.13</td>
        </tr>
        <tr>
          <td>v3 Motion Std (per sec)</td>
          <td>9</td>
          <td class="gen-price">$0.10</td>
        </tr>
        <tr>
          <td>2.6 Motion Std 720p 10sec</td>
          <td>70</td>
          <td class="gen-price">$0.53</td>
        </tr>
        <tr>
          <td>2.6 Motion Std 720p 5sec</td>
          <td>35</td>
          <td class="gen-price">$0.27</td>
        </tr>
        <tr>
          <td>2.6 Motion Pro 1080p 10sec</td>
          <td>100</td>
          <td class="gen-price">$0.76</td>
        </tr>
        <tr>
          <td>2.6 Motion Pro 1080p 5sec</td>
          <td>50</td>
          <td class="gen-price">$0.38</td>
        </tr>
        <tr>
          <td>Video Extend</td>
          <td>20</td>
          <td class="gen-price">$0.22</td>
        </tr>
        <tr>
          <td>Video Add Sound</td>
          <td>2.5</td>
          <td class="gen-price">$0.025</td>
        </tr>
        <tr>
          <td>Effects Std</td>
          <td>20</td>
          <td class="gen-price">$0.22</td>
        </tr>
        <tr>
          <td>Effects Pro</td>
          <td>35</td>
          <td class="gen-price">$0.39</td>
        </tr>
        <tr>
          <td>LipSync 5sec</td>
          <td>5</td>
          <td class="gen-price">$0.06</td>
        </tr>
        <tr>
          <td>LipSync 10sec</td>
          <td>10</td>
          <td class="gen-price">$0.11</td>
        </tr>
        <tr>
          <td>Avatar 2.0 Pro (per sec)</td>
          <td>8</td>
          <td class="gen-price">$0.09</td>
        </tr>
        <tr>
          <td>Avatar 2.0 Std (per sec)</td>
          <td>4</td>
          <td class="gen-price">$0.04</td>
        </tr>
        <tr>
          <td>Virtual Try-On</td>
          <td>5</td>
          <td class="gen-price">$0.06</td>
        </tr>
        <tr>
          <td>KOLORS 1.5/2.0/2.1 Image</td>
          <td>1</td>
          <td class="gen-price">$0.01</td>
        </tr>
        <tr>
          <td>O1 Image 1k</td>
          <td>1</td>
          <td class="gen-price">$0.01</td>
        </tr>
        <tr>
          <td>O1 Image 2k</td>
          <td>1</td>
          <td class="gen-price">$0.01</td>
        </tr>
        <tr>
          <td>O1 Video Pro 10sec</td>
          <td>70</td>
          <td class="gen-price">$0.77</td>
        </tr>
        <tr>
          <td>O1 Video Pro 5sec</td>
          <td>35</td>
          <td class="gen-price">$0.39</td>
        </tr>
        <tr>
          <td>O1 Video Std 10sec</td>
          <td>35</td>
          <td class="gen-price">$0.39</td>
        </tr>
        <tr>
          <td>O1 Video Std 5sec</td>
          <td>18</td>
          <td class="gen-price">$0.20</td>
        </tr>
        <tr>
          <td>v3 Video Pro (per sec)</td>
          <td>12</td>
          <td class="gen-price">$0.13</td>
        </tr>
        <tr>
          <td>v3 Video Std (per sec)</td>
          <td>9</td>
          <td class="gen-price">$0.10</td>
        </tr>
        <tr>
          <td>v3 Image 1k</td>
          <td>1</td>
          <td class="gen-price">$0.01</td>
        </tr>
        <tr>
          <td>v3 Image 2k</td>
          <td>2</td>
          <td class="gen-price">$0.02</td>
        </tr>
        <tr>
          <td>v3 Image 4k (VIP)</td>
          <td>4</td>
          <td class="gen-price">$0.04</td>
        </tr>
        <tr>
          <td>KOLORS v3.0 Image</td>
          <td>1</td>
          <td class="gen-price">$0.01</td>
        </tr>
      </tbody>
    </table>
  </div>
</details>

<script>
(function() {
  const klingCalculatorData = {
    plans: {
      std_monthly: { name: "Standard monthly (660 credits per month)", cost: 9, credits: 660 },
      pro_monthly: { name: "Pro monthly (3000 credits per month)", cost: 33, credits: 3000 },
      premier_monthly: { name: "Premier monthly (8000 credits per month)", cost: 81, credits: 8000 },
      ultra_monthly: { name: "Ultra monthly (26000 credits per month)", cost: 160, credits: 26000 },
      std_yearly: { name: "Standard yearly (660 credits per month)", cost: 79, credits: 7920 },
      pro_yearly: { name: "Pro yearly (3000 credits per month)", cost: 293, credits: 36000 },
      premier_yearly: { name: "Premier yearly (8000 credits per month)", cost: 729, credits: 96000 },
      ultra_yearly: { name: "Ultra yearly (26000 credits per month)", cost: 1430, credits: 312000 },
      credits: { name: "16000 credits card (2y expiration)", cost: 200, credits: 16000 },
      custom: { name: "Custom Plan", cost: 160, credits: 26000 }
    },
    generations: [
      { name: "2.6 Pro Native Audio 1080p 10sec", credits: 70 },
      { name: "2.6 Pro Native Audio 1080p 5sec", credits: 35 },
      { name: "2.6 Pro 1080p 10sec", credits: 50 },
      { name: "2.6 Pro 1080p 5sec", credits: 25 },
      { name: "2.6 Std 720p 10sec", credits: 30 },
      { name: "2.6 Std 720p 5sec", credits: 15 },
      { name: "2.5 Pro 1080p 10sec", credits: 50 },
      { name: "2.5 Pro 1080p 5sec", credits: 25 },
      { name: "2.1 Pro 1080p 10sec", credits: 70 },
      { name: "2.1 Pro 1080p 5sec", credits: 35 },
      { name: "2.1 Std 720p 10sec", credits: 40 },
      { name: "2.1 Std 720p 5sec", credits: 20 },
      { name: "2.x Master 1080p 10sec", credits: 200 },
      { name: "2.x Master 1080p 5sec", credits: 100 },
      { name: "1.6 Pro 1080p 10sec", credits: 70 },
      { name: "1.6 Pro 1080p 5sec", credits: 35 },
      { name: "1.6 Std 720p 10sec", credits: 40 },
      { name: "1.6 Std 720p 5sec", credits: 20 },
      { name: "v3 Motion Pro (per sec)", credits: 12 },
      { name: "v3 Motion Std (per sec)", credits: 9 },
      { name: "2.6 Motion Std 720p 10sec", credits: 70 },
      { name: "2.6 Motion Std 720p 5sec", credits: 35 },
      { name: "2.6 Motion Pro 1080p 10sec", credits: 100 },
      { name: "2.6 Motion Pro 1080p 5sec", credits: 50 },
      { name: "Video Extend", credits: 20 },
      { name: "Video Add Sound", credits: 2.5 },
      { name: "Effects Std", credits: 20 },
      { name: "Effects Pro", credits: 35 },
      { name: "LipSync 5sec", credits: 5 },
      { name: "LipSync 10sec", credits: 10 },
      { name: "Avatar 2.0 Pro (per sec)", credits: 8 },
      { name: "Avatar 2.0 Std (per sec)", credits: 4 },
      { name: "Virtual Try-On", credits: 5 },
      { name: "KOLORS 1.5/2.0/2.1 Image", credits: 1 },
      { name: "O1 Image 1k", credits: 1 },
      { name: "O1 Image 2k", credits: 1 },
      { name: "O1 Video Pro 10sec", credits: 70 },
      { name: "O1 Video Pro 5sec", credits: 35 },
      { name: "O1 Video Std 10sec", credits: 35 },
      { name: "O1 Video Std 5sec", credits: 18 },
      { name: "v3 Video Pro (per sec)", credits: 12 },
      { name: "v3 Video Std (per sec)", credits: 9 },
      { name: "v3 Image 1k", credits: 1 },
      { name: "v3 Image 2k", credits: 2 },
      { name: "v3 Image 4k (VIP)", credits: 4 },
      { name: "KOLORS v3.0 Image", credits: 1 }
    ]
  };

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', setupCalculator);
  } else {
    setupCalculator();
  }

  function setupCalculator() {
    const planSelect = document.getElementById('planSelect');
    const customInputs = document.getElementById('customInputs');
    const customCost = document.getElementById('customCost');
    const customCredits = document.getElementById('customCredits');
    const planName = document.getElementById('planName');
    const planCost = document.getElementById('planCost');
    const planCredits = document.getElementById('planCredits');
    const creditCost = document.getElementById('creditCost');
    const genPrices = document.querySelectorAll('.gen-price');
    
    if (!planSelect || !customInputs || !customCost || !customCredits || 
        !planName || !planCost || !planCredits || !creditCost) {
      return;
    }
    
    function updatePrices() {
      let selectedPlan;
      
      if (planSelect.value === 'custom') {
        customInputs.style.display = 'block';
        const cost = parseFloat(customCost.value) || 0;
        const credits = parseInt(customCredits.value) || 1;
        
        klingCalculatorData.plans.custom.cost = cost;
        klingCalculatorData.plans.custom.credits = credits;
        klingCalculatorData.plans.custom.name = "Custom Plan";
        
        selectedPlan = klingCalculatorData.plans.custom;
      } else {
        customInputs.style.display = 'none';
        selectedPlan = klingCalculatorData.plans[planSelect.value];
      }
      
      planName.textContent = selectedPlan.name;
      planCost.textContent = '$' + selectedPlan.cost;
      planCredits.textContent = selectedPlan.credits;
      
      const creditCostValue = selectedPlan.cost / selectedPlan.credits;
      creditCost.textContent = '$' + creditCostValue.toFixed(5);
      
      klingCalculatorData.generations.forEach((gen, index) => {
        if (index < genPrices.length) {
          const price = (gen.credits * creditCostValue).toFixed(2);
          genPrices[index].textContent = '$' + price;
        }
      });
    }
    
    planSelect.addEventListener('change', updatePrices);
    customCost.addEventListener('input', updatePrices);
    customCredits.addEventListener('input', updatePrices);
    
    updatePrices();
  }
})();
</script>

[Setup Kling](/docs/start-here/setup-kling)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(May 6, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-kling-v1.txt) <small>Feed this to your LLM to build integrations</small>

Blogs:
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [Kling Motion Control v3.0](/blog/260306)
* [Kling Multi-Shot](/blog/260216)
* [Kling API v3](/blog/260209)
* [Kling API Elements & Avatars 2.0](/blog/260112)
* [Kling API Video O1 (Omni)](/blog/260112)
* [Kling API Motion Control v2.6](/blog/260106)
* [Kling API Image O1 (Omni)](/blog/251210)
* [Kling API v2.6 with Native Audio](/blog/251204)
* [Kling API Create Video using First and Last Frames](/blog/251127)
* [Kling API Motion Control Samples](/blog/251007)
* [Kling API Text/Image-to-Video v2.5 Samples](/blog/250923)
* [Kling API Text/Image-to-Video v1.5, v1.6 and v2.0 Samples](/blog/250418)
* [Kling API Text-to-Image KOLORS Samples](/blog/250424)
* [Kling API KOLORS Elements Sample](/blog/250718)
* [Kling API Video To Sound](/blog/250808)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/kling_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/kling_api</a>

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-accounts-email ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-accounts-email
## Delete Kling API account configuration for `email`
<small>April 18, 2025</small>

---

This endpoint removes a specific Kling account from your configuration.
> **https://api.useapi.net/v1/kling/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts](/docs/api-kling-v1/post-kling-accounts) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content**

Account successfully deleted.

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Account configuration not found.

##### Examples

**Curl**
``` bash
curl -X DELETE https://api.useapi.net/v1/kling/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/accounts/${email}`; 
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
console.log("response", {status: response.status, statusText: response.statusText});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/accounts/{email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response.status_code, response.reason)
```

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-assets-uploaded ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-assets-uploaded
## Delete uploaded Kling assets
<small>May 6, 2026</small>

---

This endpoint deletes one or more assets that you previously uploaded to your Kling account via [POST /assets](/docs/api-kling-v1/post-kling-assets). Deleted assets cannot be recovered.

To delete generated assets (outputs), use [DELETE /tasks/`task_id`](/docs/api-kling-v1/del-kling-tasks-task_id) instead.
> **https://api.useapi.net/v1/kling/assets/uploaded/?email=`email`&id=`id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is **required** — the previously configured account email (see [POST /accounts](/docs/api-kling-v1/post-kling-accounts)).

- `id` is **required** — the uploaded asset ID, or a comma-separated list of up to 10 numeric IDs.   
  Asset IDs are returned by [GET /assets/uploaded](/docs/api-kling-v1/get-kling-assets-uploaded) in the `id` field of each item in `uploadAssetsList`.

##### Responses

**200**
**200 OK**
```json
{
  "deleted": 1,
  "ids": ["869218167527833688"]
}
```

The response indicates how many assets were deleted and their IDs.

**400**
**400 Bad Request**
```json
{
  "error": "Parameter id (...) must be a numeric string or a comma-separated list of up to 10 numeric strings"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  deleted: number     // Number of uploaded assets deleted
  ids: string[]       // Array of deleted asset IDs
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/assets/uploaded/?email=user@example.com&id=869218167527833688" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const id = "869218167527833688"; // single id, or "id1,id2,id3" up to 10
const apiUrl = `https://api.useapi.net/v1/kling/assets/uploaded/?email=${email}&id=${id}`;
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
id = "869218167527833688" # single id, or "id1,id2,id3" up to 10
apiUrl = f"https://api.useapi.net/v1/kling/assets/uploaded/?email={email}&id={id}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-avatars-avatarId ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-avatars-avatarId
## Delete avatar
<small>January 12, 2026</small>

---

This endpoint deletes a specific avatar by its ID. Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to list your avatars and get their IDs.

Note: You can only delete personal avatars created via [POST /avatars](/docs/api-kling-v1/post-kling-avatars). System template avatars cannot be deleted.
> **https://api.useapi.net/v1/kling/avatars/`avatarId`?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `avatarId` is **required**, the avatar ID to delete.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "deleted": null
}
```

A `null` value indicates successful deletion.

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

##### Model
```typescript
{ // TypeScript
  deleted: null  // null indicates success
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/avatars/123456789012?email=user@example.com" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const avatarId = "123456789012";
const apiUrl = `https://api.useapi.net/v1/kling/avatars/${avatarId}?email=${email}`;
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
avatarId = "123456789012"
apiUrl = f"https://api.useapi.net/v1/kling/avatars/{avatarId}?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-elements-elementId ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-elements-elementId
## Delete element
<small>January 12, 2026</small>

---

This endpoint deletes a specific element by its ID. Use [GET /elements](/docs/api-kling-v1/get-kling-elements) to list your elements and get their IDs.
> **https://api.useapi.net/v1/kling/elements/`elementId`?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `elementId` is **required**, the element ID to delete.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "deleted": 1
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

##### Model
```typescript
{ // TypeScript
  deleted: number
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const elementId = "u_123456789012345";
const apiUrl = `https://api.useapi.net/v1/kling/elements/${elementId}?email=${email}`;
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
elementId = "u_123456789012345"
apiUrl = f"https://api.useapi.net/v1/kling/elements/{elementId}?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-scheduler-task_id ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-scheduler-task_id
## Cancel a running task
<small>April 18, 2025</small>

---

This endpoint cancels a running API task from being tracked by the scheduler. The task will still be executed by Kling, but the API will no longer track its progress.
> **https://api.useapi.net/v1/kling/scheduler/`task_id`**

The `task_id` value should be a numeric identifier of the task you want to cancel. You can get task IDs from [GET /scheduler](/docs/api-kling-v1/get-kling-scheduler).

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content**

Task was successfully canceled.

**400**
**400 Bad Request**
```json
{
  "error": "Error ..."
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "Unable to locate running task_id 123456789"
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/scheduler/123456789" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const taskId = "123456789";
const apiUrl = `https://api.useapi.net/v1/kling/scheduler/${taskId}`; 
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
console.log("response", {status: response.status, statusText: response.statusText});
```

**Python**
``` python
import requests
token = "API token"
task_id = "123456789"
apiUrl = f"https://api.useapi.net/v1/kling/scheduler/{task_id}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response.status_code, response.reason)
```

=== URL: https://useapi.net/docs/api-kling-v1/del-kling-tasks-task_id ===
Document URL: https://useapi.net/docs/api-kling-v1/del-kling-tasks-task_id
## Delete Kling Task
<small>October 7, 2025</small>

---

This endpoint deletes a specific task and all its associated works (outputs) by task ID. Deleted tasks and works cannot be recovered. If the task has multiple works (e.g., multiple variations), all of them will be deleted.
> **https://api.useapi.net/v1/kling/tasks/`task_id`?…**

The `task_id` value should be a numeric identifier of the task you want to delete.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "deleted": 1,
  "workIds": [987654321]
}
```

The response indicates how many works were deleted and their IDs.

**400**
**400 Bad Request**
```json
{
  "error": "Invalid task_id parameter"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Task was not found or has no associated works.

```json
{
  "error": "No works found for task 123456789"
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  deleted: number     // Number of works deleted
  workIds: number[]   // Array of deleted work IDs
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const taskId = "123456789";
const apiUrl = `https://api.useapi.net/v1/kling/tasks/${taskId}?email=${email}`;
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
task_id = "123456789"
apiUrl = f"https://api.useapi.net/v1/kling/tasks/{task_id}?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts-email ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts-email
## Retrieve Kling API account configuration and balance for `email`
<small>April 18, 2025 (June 23, 2025)</small>

---

This endpoint retrieves the configuration and balance information for a specific Kling account.
> **https://api.useapi.net/v1/kling/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts](/docs/api-kling-v1/post-kling-accounts) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "email": "user@example.com",
  "session": {
    "userId": "user12345",
    "ExpireTime": 123456789,
    "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
  },
  "maxJobs": 5,
  "password": "…secured…",
  "balance": {
      "points": [
          {
              "orderId": "123456789",
              "type": "plan",
              "amount": 66000,
              "balance": 56000,
              "startTime": 123456789,
              "endTime": 123456789
          }
      ],
      "tickets": [],
      "nextApplyTime": 123456789,
      "total": 56000
  }  
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Account configuration not found. To create configuration use [POST /accounts](/docs/api-kling-v1/post-kling-accounts).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string
  session: {
    userId: string
    ExpireTime: number
    ExpireTimeUTC: string
  }
  maxJobs: number
  password: string
  balance: {
    points: Array<{
        orderId: string
        type: string
        amount: number
        balance: number
        startTime: number
        endTime: number
    }>
    tickets: Array<any>
    nextApplyTime: number
    total: number
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/kling/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/accounts/${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/accounts/{email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts
## Retrieve Kling API accounts configuration
<small>April 18, 2025</small>

---

For your convenience, you can specify your Kling configuration values under your Kling account. If you specify multiple Kling accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Kling.

This endpoint retrieves the complete list of configured API accounts for Kling.
> **https://api.useapi.net/v1/kling/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "<email #1>": {
        "email": "<email #1>",
        "session": {
            "userId": "user12345",
            "ExpireTime": 123456789,
            "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
        },
        "maxJobs": 8,
        "password": "…secured…"
    },
    "<email #2>": {
        "email": "<email #2>",
        "session": {
            "userId": "user67890",
            "ExpireTime": 123456789,
            "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
        },
        "maxJobs": 3,
        "password": "…secured…"
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts](/docs/api-kling-v1/post-kling-accounts).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [email: string]: {
        email: string
        session: {
            userId: string
            ExpireTime: number
            ExpireTimeUTC: string
        }
        maxJobs: number
        password: string
    }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/kling/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/kling/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/kling/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-download ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-download
## Download Kling assets without watermarks
<small>April 18, 2025 (June 27, 2025)</small>

---

This endpoint allows you to download assets from your *paid* Kling account without watermarks by providing the work IDs.
> **https://api.useapi.net/v1/kling/assets/download?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `workIds` is **required**, specify the IDs of works to download.   
  Can be a single numeric string or a comma-separated list of numeric strings (e.g., "123456789" or "123456789,987654321").  
  These IDs can be obtained from the `workId` field in the `works` array returned by the [GET /assets](/docs/api-kling-v1/get-kling-assets), [GET /tasks](/docs/api-kling-v1/get-kling-tasks) or [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) endpoint.

- `fileTypes` is optional, specify comma-separated file types you want to download (e.g., "MP4" or "MP4,WAV"). If not provided, all available files for the given workIds will be downloaded as a singe .zip file.  
  Supported file types: `MP4`, `MP3`, `WAV`, `PNG`.  

**Note:** If a single `workId` is provided with a single `fileTypes` value, the cdnUrl will point to an actual asset file. If multiple `workIds` are provided or `fileTypes` is omitted or has multiple values, the cdnUrl will point to a .zip file containing all requested assets/files.

##### Responses 

**200**
**200 OK**
```json
{
  "cdnUrl": "https://kling.klingai.com/.../download_result.zip",
  "status": "success"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Invalid parameters"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript
  cdnUrl: string // URL to download the asset(s), .zip for multiple workIds
  status: string // "success" when successful
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/assets/download?email=user@example.com&workIds=123456789,987654321" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const workIds = "123456789,987654321";
const apiUrl = `https://api.useapi.net/v1/kling/assets/download?email=${email}&workIds=${workIds}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
workIds = "123456789,987654321"
apiUrl = f"https://api.useapi.net/v1/kling/assets/download?email={email}&workIds={workIds}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-uploaded ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-uploaded
## Retrieve uploaded Kling assets
<small>August 8, 2025 (May 6, 2026)</small>

---

This endpoint retrieves assets that you have uploaded to your Kling account, as opposed to generated assets.
> **https://api.useapi.net/v1/kling/assets/uploaded/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `pageNum` is optional, specify the page number to retrieve.   
  Default `1`.

- `pageSize` is optional, specify the number of items per page.   
  Default `20`.

- `contentType` is optional, type of content to retrieve.   
  Supported values: `video`, `image`, or `audio`.

- `fileName` is optional, filter by file name (keyword search).

- `sort` is optional, sort direction by upload time.   
  Supported values: `asc`, `desc`. Default `desc`.

##### Responses 

**200**
**200 OK**
```json
{
  "uploadAssetsList": [
    {
      "id": "1234567890",
      "name": "abcdef12345.mp4",
      "userId": 12345,
      "contentType": "video",
      "resource": {
        "resource": "https://v15-kling.klingai.com/….mp4",
        "height": 1080,
        "width": 720,
        "duration": 9040,
        "resourceKey": ""
      },
      "cover": {
        "resource": "https://v15-kling.klingai.com/…",
        "height": 1080,
        "width": 720,
        "duration": 0,
        "resourceKey": ""
      },
      "createTime": 1754630473303,
      "updateTime": 1754630473303,
      "favored": false,
      "extraInfo": "{}",
      "entrance": ""
    },
    {
      "id": "1234567890",
      "name": "abcdef12345.mp4",
      "userId": 12345,
      "contentType": "image",
      "resource": {
        "resource": "https://v15-kling.klingai.com/…",
        "height": 1080,
        "width": 720,
        "duration": 0,
        "resourceKey": ""
      },
      "cover": {
        "resource": "",
        "height": 1,
        "width": 1,
        "duration": 0,
        "resourceKey": ""
      },
      "createTime": 1754627757354,
      "updateTime": 1754627757354,
      "favored": false,
      "extraInfo": "{}",
      "entrance": ""
    }
  ]
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Invalid parameters"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{ // TypeScript, all fields are optional
    uploadAssetsList: {
        id: string            // Unique asset identifier
        name: string          // Generated unique filename
        userId: number        // User ID who uploaded the asset
        contentType: string   // "video", "image", or "audio"
        resource: {
            resource: string    // URL of the uploaded asset
            height: number      // Height in pixels
            width: number       // Width in pixels  
            duration: number    // Duration in milliseconds (0 for images)
            resourceKey: string // Resource key (usually empty)
        }
        cover: {
            resource: string    // URL of cover image (empty for images)
            height: number      // Cover height (1 for images without cover)
            width: number       // Cover width (1 for images without cover)
            duration: number    // Cover duration (always 0)
            resourceKey: string // Cover resource key (usually empty)
        }
        createTime: number      // Upload timestamp
        updateTime: number      // Last update timestamp
        favored: boolean        // Whether asset is favorited
        extraInfo: string       // Extra information as JSON string
        entrance: string        // Entry point (usually empty)
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-assets ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets
## Retrieve Kling assets
<small>April 18, 2025 (May 6, 2026)</small>

---

This endpoint retrieves generated assets from your Kling account.
> **https://api.useapi.net/v1/kling/assets/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `pageNum` is optional, specify the page number to retrieve.   
  Default `1`.

- `pageSize` is optional, specify the number of items per page.   
  Default `40`.

- `contentType` is optional, type of content to retrieve.   
  Supported values: `video`, `image`, or `audio`.

- `sort` is optional, sort direction by creation time.   
  Supported values: `asc`, `desc`. Default `desc`.

##### Responses 

**200**
**200 OK**
```json
{
  "limitations": [
    {
      "type": "mmu_txt2img_aiweb",
      "remaining": 10000,
      "limit": 10000
    },
    {
      "type": "m2v_txt2video_hq",
      "remaining": 10000,
      "limit": 10000
    },
    {
      "type": "m2v_img2video_hq",
      "remaining": 10000,
      "limit": 10000
    }
  ],
  "history": [
    {
      "works": [
        {
          "workId": 123456789,
          "workItemId": 0,
          "taskId": 123456789,
          "userId": 12345,
          "type": "m2v_img2video_hq",
          "status": 99,
          "contentType": "video",
          "resource": {
            "resource": "https://s21-kling.klingai.com/....mp4",
            "height": 1268,
            "width": 724,
            "duration": 5041,
            "resourceKey": ""
          },
          "cover": {
            "resource": "https://s21-kling.klingai.com/....jpg",
            "height": 1268,
            "width": 724,
            "duration": 0,
            "resourceKey": ""
          },
          "starNum": 0,
          "cloneCount": 0,
          "reportNum": 0,
          "createTime": 1744858514515,
          "taskInfo": {
            "type": "m2v_img2video_hq",
            "inputs": [
              {
                "name": "input",
                "inputType": "URL",
                "token": null,
                "blobStorage": null,
                "url": "https://s21-kling.klingai.com/....jpg",
                "cover": null,
                "fromWorkId": null,
                "fromUploadId": null
              }
            ],
            "arguments": [
              {
                "name": "prompt",
                "value": "A person dancing"
              },
              {
                "name": "negative_prompt",
                "value": ""
              },
              {
                "name": "duration",
                "value": "5"
              },
              {
                "name": "kling_version",
                "value": "2.0"
              }
            ],
            "extraArgs": {},
            "callbackPayloads": [],
            "scene": "NORMAL_CREATION"
          },
          "selfAttitude": "unknown",
          "selfComment": {
            "rate": 0,
            "tags": [],
            "content": "",
            "prompts": []
          },
          "favored": false,
          "starred": false,
          "publishStatus": "unpublished",
          "deleted": false,
          "publishTime": 0,
          "submitTime": 1744858514515,
          "lipSyncStatus": 99,
          "downloadInfo": {
            "fileTypes": [
              {
                "type": "MP4",
                "watermark": true
              }
            ]
          },
          "allowPublish": true
        }
      ],
      "task": {
        "id": 123456789,
        "userId": 12345,
        "type": "m2v_img2video_hq",
        "scene": "NORMAL_CREATION",
        "status": 99,
        "taskInfo": {
          "type": "m2v_img2video_hq",
          "inputs": [
            {
              "name": "input",
              "inputType": "URL",
              "token": null,
              "blobStorage": null,
              "url": "https://s21-kling.klingai.com/....jpg",
              "cover": null,
              "fromWorkId": null,
              "fromUploadId": null
            }
          ],
          "arguments": [
            {
              "name": "prompt",
              "value": "A person dancing"
            },
            {
              "name": "negative_prompt",
              "value": ""
            },
            {
              "name": "duration",
              "value": "5"
            },
            {
              "name": "kling_version",
              "value": "2.0"
            }
          ],
          "extraArgs": {},
          "callbackPayloads": [],
          "scene": "NORMAL_CREATION"
        },
        "favored": false,
        "deleted": false,
        "viewed": true,
        "createTime": 1744858514499,
        "updateTime": 1744858823172,
        "viewTime": 1744916388016
      },
      "etaTime": 0,
      "etaTimeOverSla": false,
      "queuingEtaTime": 0,
      "originEtaTime": 0,
      "originQueuingEtaTime": 0,
      "currentTimestamp": 1744955215247
    }
  ],
  "userPoints": {
    "points": [
      {
        "orderId": "123456789",
        "type": "plan",
        "amount": 300000,
        "balance": 190500,
        "startTime": 1744081611119,
        "endTime": 1746760011119
      }
    ],
    "total": 190500
  },
  "userTickets": {
    "ticket": [
      {
        "orderId": "123456789",
        "type": "priority",
        "packageType": "reward",
        "amount": 1,
        "balance": 1,
        "startTime": 1744046060883,
        "endTime": 1746724460883
      },
      {
        "orderId": "123456789",
        "type": "extend",
        "packageType": "reward",
        "amount": 2,
        "balance": 2,
        "startTime": 1744046060883,
        "endTime": 1746724460883
      },
      {
        "orderId": "123456789",
        "type": "hq_5s",
        "packageType": "reward",
        "amount": 3,
        "balance": 3,
        "startTime": 1744046060883,
        "endTime": 1746724460883
      }
    ]
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Invalid parameters"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response.

```typescript
{ // TypeScript, all fields are optional
    limitations: {
        type: string
        remaining: number
        limit: number
    }[]
    history: {
        works: {
            workId: number
            workItemId: number
            taskId: number
            userId: number
            type: string
            status: number
            contentType: string
            resource: {
                resource: string
                height: number
                width: number
                duration: number
                resourceKey: string
            }
            cover: {
                resource: string
                height: number
                width: number
                duration: number
                resourceKey: string
            }
            starNum: number
            cloneCount: number
            reportNum: number
            createTime: number
            taskInfo: {
                type: string
                inputs: {
                    name: string
                    inputType: string
                    token: string | null
                    blobStorage: string | null
                    url: string
                    cover: string | null
                    fromWorkId: number | null
                    fromUploadId: number | null
                }[]
                arguments: {
                    name: string
                    value: string
                }[]
                extraArgs: Record<string, any>
                callbackPayloads: any[]
                scene: string
            }
            selfAttitude: string
            selfComment: {
                rate: number
                tags: any[]
                content: string
                prompts: any[]
            }
            favored: boolean
            starred: boolean
            publishStatus: string
            deleted: boolean
            publishTime: number
            submitTime: number
            lipSyncStatus: number
            downloadInfo: {
                fileTypes: {
                    type: string
                    watermark: boolean
                }[]
            }
            allowPublish: boolean
        }[]
        task: {
            id: number
            userId: number
            type: string
            scene: string
            status: number
            taskInfo: {
                type: string
                inputs: {
                    name: string
                    inputType: string
                    token: string | null
                    blobStorage: string | null
                    url: string
                    cover: string | null
                    fromWorkId: number | null
                    fromUploadId: number | null
                }[]
                arguments: {
                    name: string
                    value: string
                }[]
                extraArgs: Record<string, any>
                callbackPayloads: any[]
                scene: string
            }
            favored: boolean
            deleted: boolean
            viewed: boolean
            createTime: number
            updateTime: number
            viewTime: number
        }
        etaTime: number
        etaTimeOverSla: boolean
        queuingEtaTime: number
        originEtaTime: number
        originQueuingEtaTime: number
        currentTimestamp: number
    }[]
    userPoints: {
        points: {
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }[]
        total: number
    }
    userTickets: {
        ticket: {
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }[]
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/assets/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/assets/?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars
## List avatars
<small>January 12, 2026</small>

---

This endpoint retrieves a list of avatars. You can list either your personal saved avatars or browse system-provided templates.

Avatars are digital characters that can be animated with lip-sync using [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video).
> **https://api.useapi.net/v1/kling/avatars/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `type` is optional, the type of avatars to list.
  Supported values: `personal` (default), `templates`.
  - `personal`: Your saved avatars created via [POST /avatars](/docs/api-kling-v1/post-kling-avatars)
  - `templates`: System-provided avatar templates

##### Responses

**200**
**200 OK**

**Personal avatars response (type=personal):**
```json
[
  {
    "id": "123456789012",
    "nickname": "My Fashion Avatar",
    "prompt": "Elegant woman in professional attire",
    "scene": "advertising_marketing",
    "imageResources": [
      {
        "url": "https://s21-kling.klingai.com/ai-platform/.../avatar.jpg",
        "sourceFrom": 2
      }
    ],
    "ttsSpeaker": "speaker_id_123",
    "ttsSpeed": "1",
    "ttsEmotionKey": "neutral",
    "createTime": 1736640000000,
    "updateTime": 1736640000000
  }
]
```

**Templates response (type=templates):**
```json
[
  {
    "id": "12345",
    "name": "Business Woman",
    "imageResources": [
      {
        "url": "https://s21-kling.klingai.com/ai-platform/.../template.jpg"
      }
    ],
    "prompt": "Professional businesswoman in formal attire"
  }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
Array<{
  id: string
  nickname?: string
  name?: string
  prompt: string
  scene?: string
  imageResources: {
    url: string
    sourceFrom?: number
  }[]
  ttsSpeaker?: string
  ttsSpeed?: string
  ttsEmotionKey?: string
  createTime?: number
  updateTime?: number
}>
```

##### Avatar ID Format

- **Personal avatars** have long IDs (more than 8 digits), e.g., `123456789012`
- **Template avatars** have short IDs (8 digits or fewer), e.g., `12345`

This distinction is used internally when generating avatar videos.

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/avatars/?email=user@example.com&type=personal" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/avatars/?email=${email}&type=personal`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/avatars/?email={email}&type=personal"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-elementId ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-elementId
## Retrieve element by ID
<small>January 12, 2026 (February 9, 2026)</small>

---

This endpoint retrieves details for a specific element by its ID. Use [GET /elements](/docs/api-kling-v1/get-kling-elements) to list all your elements and get their IDs.
> **https://api.useapi.net/v1/kling/elements/`elementId`?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `elementId` is **required**, the element ID to retrieve.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "id": "u_123456789012345",
  "name": "FashionLady ABC12",
  "userId": 12345678,
  "type": "IMAGE",
  "description": "Elegant woman in red dress",
  "cover": {
    "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
    "width": 768,
    "height": 1365,
    "resourceKey": "cover",
    "cover": true,
    "slotKey": ""
  },
  "resources": [
    { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
    { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" },
    { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" },
    { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" }
  ],
  "tagList": [],
  "favored": false,
  "official": false,
  "createTime": 1736640000000,
  "updateTime": 1736640000000
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  id: string
  name: string
  userId: number
  type: 'IMAGE' | 'VIDEO'
  description: string
  cover: {
    resource: string
    width: number
    height: number
    resourceKey: 'cover' | 'secondary' | 'video'
    cover: boolean
    slotKey: string
  }
  resources: {
    resource: string
    width: number
    height: number
    resourceKey: 'cover' | 'secondary' | 'video'
    cover: boolean
    slotKey: string
    voice: {
      id: number
      name: string
      official: boolean
      resource: object
    }
  }[]
  tagList: object[]
  voice: {
    id: number
    name: string
    official: boolean
    resource: object
  }
  currentVersion: number
  createTime: number
  updateTime: number
  favored: boolean
  official: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const elementId = "u_123456789012345";
const apiUrl = `https://api.useapi.net/v1/kling/elements/${elementId}?email=${email}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
elementId = "u_123456789012345"
apiUrl = f"https://api.useapi.net/v1/kling/elements/{elementId}?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-tags ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-tags
## Retrieve available element tags
<small>January 12, 2026</small>

---

This endpoint retrieves available element category tags. Tags are used to categorize elements when creating them via [POST /elements](/docs/api-kling-v1/post-kling-elements) and for filtering when listing elements via [GET /elements](/docs/api-kling-v1/get-kling-elements).
> **https://api.useapi.net/v1/kling/elements/tags/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "tagList": [
    {
      "id": "o_102",
      "tagKey": "character",
      "name": "Characters",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_103",
      "tagKey": "animal",
      "name": "Animals",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_104",
      "tagKey": "prop",
      "name": "Items",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_105",
      "tagKey": "costume",
      "name": "Costumes",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_106",
      "tagKey": "scene",
      "name": "Scenes",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_107",
      "tagKey": "effect",
      "name": "Effects",
      "official": true,
      "type": "element"
    },
    {
      "id": "o_108",
      "tagKey": "others",
      "name": "Others",
      "official": true,
      "type": "element"
    }
  ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  tagList: {
    id: string
    tagKey: string
    name: string
    official: boolean
    type: string
  }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/elements/tags/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/elements/tags/?email=${email}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/elements/tags/?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-voices ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-voices
## Retrieve available element voices
<small>February 9, 2026</small>

---

This endpoint retrieves available official voices for elements. Voices can be assigned to elements when creating them via [POST /elements](/docs/api-kling-v1/post-kling-elements). Only elements with the `character` tag support voice assignment.
> **https://api.useapi.net/v1/kling/elements/voices/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

**200**
**200 OK**
```json
{
  "voices": [
    {
      "id": 1,
      "name": "Vivid Girl"
    },
    {
      "id": 2,
      "name": "Gentle Lady"
    },
    {
      "id": 3,
      "name": "Charming Uncle"
    }
  ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  voices: {
    id: number
    name: string
  }[]
}
```

Use the `id` or `name` value in the `voice` parameter when creating VIDEO elements via [POST /elements](/docs/api-kling-v1/post-kling-elements).

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/elements/voices/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/elements/voices/?email=${email}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/elements/voices/?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements
## List elements
<small>January 12, 2026 (February 9, 2026)</small>

---

This endpoint retrieves a list of your custom elements. Elements are saved character/object references that can be reused across multiple generations in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) using the `@element_N` syntax.
> **https://api.useapi.net/v1/kling/elements/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `pageNum` is optional, the page number to retrieve.
  Default: `1`. Must be `1` or greater.

- `pageSize` is optional, the number of elements per page.
  Range: `1` to `100`. Default: `50`.

- `tag` is optional, filter elements by tag.
  Use [GET /elements/tags](/docs/api-kling-v1/get-kling-elements-tags) to get available tags.

- `official` is optional, filter to show only official/system elements.
  Default: `false`.

- `favored` is optional, filter to show only favored elements.
  Default: `false`.

- `sortDirection` is optional, sort order for results.
  Supported values: `ASC`, `DESC` (default).

##### Responses

**200**
**200 OK**
```json
{
  "elementsList": [
    {
      "id": "u_123456789012345",
      "name": "FashionLady ABC12",
      "userId": 12345678,
      "type": "IMAGE",
      "description": "Elegant woman in red dress",
      "cover": {
        "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
        "width": 768,
        "height": 1365,
        "resourceKey": "cover",
        "cover": true,
        "slotKey": ""
      },
      "resources": [
        { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
        { "resource": ".../side.png", "resourceKey": "secondary", "slotKey": "side" }
      ],
      "tagList": [],
      "favored": false,
      "official": false,
      "createTime": 1736640000000,
      "updateTime": 1736640000000
    }
  ],
  "pageNum": 1,
  "pageSize": 50,
  "total": 3
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  elementsList: {
    id: string
    name: string
    userId: number
    type: 'IMAGE' | 'VIDEO'
    description: string
    cover: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
    }
    resources: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
      voice: {
        id: number
        name: string
        official: boolean
        resource: object
      }
    }[]
    tagList: object[]
    voice: {
      id: number
      name: string
      official: boolean
      resource: object
    }
    currentVersion: number
    createTime: number
    updateTime: number
    favored: boolean
    official: boolean
  }[]
  pageNum: number
  pageSize: number
  total: number
}
```

##### Usage in Omni Endpoints

Once you have element IDs, you can reference them in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni):

```json
{
  "prompt": "Character @element_1 walking through a beautiful garden",
  "element_1": "u_123456789012345"
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/elements/?email=user@example.com&pageSize=10" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/elements/?email=${email}&pageSize=10`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/elements/?email={email}&pageSize=10"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler-available ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler-available
## Retrieve available capacity
<small>April 18, 2025</small>

---

This endpoint retrieves information about available capacity and currently running API tasks.
> **https://api.useapi.net/v1/kling/scheduler/available**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "executing": [
    {
      "id": 123456789,
      "email": "user1@example.com",
      "started": "2025-04-18T12:34:56.789Z",
      "elapsed": "03:45",
      "replyUrl": "https://example.com/webhook",
      "replyRef": "reference-id"
    }
  ],
  "available": [
    {
      "email": "user1@example.com",
      "maxJobs": 5,
      "executing": 1,
      "available": 4
    },
    {
      "email": "user2@example.com",
      "maxJobs": 3,
      "executing": 0,
      "available": 3
    }
  ]
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Error ..."
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  executing: {
    id: number // Task ID
    email: string // Account email
    started: string // ISO timestamp of when the task started
    elapsed: string // Elapsed time in MM:SS format
    replyUrl: string // Webhook URL to notify when the task completes
    replyRef: string // Reference ID for the webhook
  }[]
  available: {
    email: string // Kling account email
    maxJobs: number // Maximum number of concurrent jobs configured
    executing: number // Number of jobs currently executing
    available: number // Number of available job slots
  }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/kling/scheduler/available"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/kling/scheduler/available"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler
## Retrieve running tasks
<small>April 18, 2025</small>

---

This endpoint retrieves information about currently running API tasks.
> **https://api.useapi.net/v1/kling/scheduler**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
[
  {
    "id": 123456789,
    "email": "user@example.com",
    "started": "2025-04-18T12:34:56.789Z",
    "elapsed": "03:45",
    "replyUrl": "https://example.com/webhook",
    "replyRef": "reference-id"
  },
  {
    "id": 987654321,
    "email": "user@example.com",
    "started": "2025-04-18T12:45:67.890Z",
    "elapsed": "02:34",
    "replyUrl": "https://example.com/webhook",
    "replyRef": "reference-id-2"
  }
]
```

**400**
**400 Bad Request**
```json
{
  "error": "Error ..."
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  id: number // Task ID
  email: string // Account email
  started: string // ISO timestamp of when the task started
  elapsed: string // Elapsed time in MM:SS format
  replyUrl: string // Webhook URL to notify when the task completes
  replyRef: string // Reference ID for the webhook
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/scheduler" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/kling/scheduler"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/kling/scheduler"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id
## Retrieve specific Kling task
<small>April 18, 2025 (December 10, 2025)</small>

---

This endpoint retrieves information about a specific task by its ID.
> **https://api.useapi.net/v1/kling/tasks/`task_id`?…**

The `task_id` value should be a numeric identifier of the task you want to retrieve.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

**200**
**200 OK**
```json
{
  "status": 99,
  "status_name": "succeed",
  "status_final": true,
  "etaTime": 0,
  "etaTimeOverSla": false,
  "queuingEtaTime": 0,
  "originEtaTime": 0,
  "originQueuingEtaTime": 0,
  "message": "success",
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2video_hq",
    "scene": "NORMAL_CREATION",
    "status": 99,
    "status_name": "succeed",
    "status_final": true,
    "taskInfo": {
      "type": "m2v_img2video_hq",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/....jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A person dancing"
        },
        {
          "name": "negative_prompt",
          "value": ""
        },
        {
          "name": "duration",
          "value": "5"
        },
        {
          "name": "kling_version",
          "value": "2.0"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": true,
    "createTime": 1744858514499,
    "updateTime": 1744858823172,
    "viewTime": 1744916388016
  },
  "works": [
    {
      "workId": 123456789,
      "workItemId": 0,
      "taskId": 123456789,
      "userId": 12345,
      "type": "m2v_img2video_hq",
      "status": 99,
      "status_name": "succeed",
      "status_final": true,
      "contentType": "video",
      "resource": {
        "resource": "https://s21-kling.klingai.com/....mp4",
        "height": 1268,
        "width": 724,
        "duration": 5041,
        "resourceKey": ""
      },
      "cover": {
        "resource": "https://s21-kling.klingai.com/....jpg",
        "height": 1268,
        "width": 724,
        "duration": 0,
        "resourceKey": ""
      },
      "starNum": 0,
      "cloneCount": 0,
      "reportNum": 0,
      "createTime": 1744858514515,
      "taskInfo": {
        "type": "m2v_img2video_hq",
        "inputs": [
          {
            "name": "input",
            "inputType": "URL",
            "token": null,
            "blobStorage": null,
            "url": "https://s21-kling.klingai.com/....jpg",
            "cover": null,
            "fromWorkId": null,
            "fromUploadId": null
          }
        ],
        "arguments": [
          {
            "name": "prompt",
            "value": "A person dancing"
          },
          {
            "name": "negative_prompt",
            "value": ""
          },
          {
            "name": "duration",
            "value": "5"
          },
          {
            "name": "kling_version",
            "value": "2.0"
          }
        ],
        "extraArgs": {},
        "callbackPayloads": [],
        "scene": "NORMAL_CREATION"
      },
      "selfAttitude": "unknown",
      "selfComment": {
        "rate": 0,
        "tags": [],
        "content": "",
        "prompts": []
      },
      "favored": false,
      "starred": false,
      "publishStatus": "unpublished",
      "deleted": false,
      "publishTime": 0,
      "submitTime": 1744858514515,
      "lipSyncStatus": 99,
      "downloadInfo": {
        "fileTypes": [
          {
            "type": "MP4",
            "watermark": true
          }
        ]
      },
      "allowPublish": true
    }
  ],
  "currentTimestamp": 1744955215247
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Invalid task_id parameter"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Task was either deleted or failed due to moderation, or your account did not have enough credits. Check your KLING account balance [GET accounts/`email`](/docs/api-kling-v1/get-kling-accounts-email)

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

##### Model 

List of known `status` values:

| status | status_name | status_final  | Notes                                          |
|--------|-------------|---------------|------------------------------------------------|
| 5      | submitted   | false         |                                                |
| 6      | failed      | true          | Change the input prompt and try again          |
| 7      | failed      | true          | The input prompt contains sensitive words      |
| 9      | failed      | true          | Change the input prompt and try again          |
| 10     | processing  | false         |                                                |
| 50     | failed      | true          | Change the input prompt and try again          |
| 53     | failed      | true          | Your account does not support this feature     |
| 54     | failed      | true          | The queue for the free plan is busy now        |
| 58     | failed      | true          | The queue for your plan is busy now. Wait until running tasks are completed and retry, or upgrade your plan. |
| 99     | succeed     | true          |                                                |

Calculate estimated time left in milliseconds as `etaTime - currentTimestamp`. When the task is complete, `etaTime` will be `0`.

To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response.

```typescript
{ // TypeScript, all fields are optional
  status: number
  status_name: string
  status_final: boolean
  etaTime: number
  etaTimeOverSla: boolean
  queuingEtaTime: number
  originEtaTime: number
  originQueuingEtaTime: number
  message: string
  task: {
    id: number
    userId: number
    type: string
    scene: string
    status: number
    status_name: string
    status_final: boolean
    taskInfo: {
      type: string
      inputs: {
        name: string
        inputType: string
        token: string | null
        blobStorage: string | null
        url: string
        cover: string | null
        fromWorkId: number | null
      }[]
      arguments: {
        name: string
        value: string
      }[]
      extraArgs: Record<string, any>
      callbackPayloads: any[]
      scene: string
    }
    favored: boolean
    deleted: boolean
    viewed: boolean
    createTime: number
    updateTime: number
    viewTime: number
  }
  works: {
    workId: number
    workItemId: number
    taskId: number
    userId: number
    type: string
    status: number
    status_name: string
    status_final: boolean
    contentType: string
    resource: {
      resource: string
      height: number
      width: number
      duration: number
      resourceKey: string
    }
    cover: {
      resource: string
      height: number
      width: number
      duration: number
      resourceKey: string
    }
    starNum: number
    cloneCount: number
    reportNum: number
    createTime: number
    taskInfo: {
      type: string
      inputs: {
        name: string
        inputType: string
        token: string | null
        blobStorage: string | null
        url: string
        cover: string | null
        fromWorkId: number | null
        fromUploadId: number | null
      }[]
      arguments: {
        name: string
        value: string
      }[]
      extraArgs: Record<string, any>
      callbackPayloads: any[]
      scene: string
    }
    selfAttitude: string
    selfComment: {
      rate: number
      tags: any[]
      content: string
      prompts: any[]
    }
    favored: boolean
    starred: boolean
    publishStatus: string
    deleted: boolean
    publishTime: number
    submitTime: number
    lipSyncStatus: number
    downloadInfo: {
      fileTypes: {
        type: string
        watermark: boolean
      }[]
    }
    allowPublish: boolean
  }[]
  currentTimestamp: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const taskId = "123456789";
const apiUrl = `https://api.useapi.net/v1/kling/tasks/${taskId}?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
task_id = "123456789"
apiUrl = f"https://api.useapi.net/v1/kling/tasks/{task_id}?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks
## Retrieve Kling tasks
<small>April 18, 2025</small>

---

This endpoint retrieves a list of tasks from your Kling account.
> **https://api.useapi.net/v1/kling/tasks/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `contentType` is optional, filter tasks by content type.  
  Supported values: `video`, `image`, or `audio`.

- `pageSize` is optional, specify the number of tasks to return.  

- `createdBefore` is optional, timestamp (in milliseconds) to get tasks created before this time.   
  Cannot be used with `createdAfter`.

- `createdAfter` is optional, timestamp (in milliseconds) to get tasks created after this time.   
  Cannot be used with `createdBefore`.

##### Responses 

**200**
**200 OK**
```json
{
  "history": [
    {
      "works": [
        {
          "workId": 123456789,
          "workItemId": 0,
          "taskId": 123456789,
          "userId": 12345,
          "type": "m2v_img2video_hq",
          "status": 99,
          "status_name": "succeed",
          "status_final": true          
          "contentType": "video",
          "resource": {
            "resource": "https://s21-kling.klingai.com/....mp4",
            "height": 1268,
            "width": 724,
            "duration": 5041,
            "resourceKey": ""
          },
          "cover": {
            "resource": "https://s21-kling.klingai.com/....jpg",
            "height": 1268,
            "width": 724,
            "duration": 0,
            "resourceKey": ""
          },
          "starNum": 0,
          "cloneCount": 0,
          "reportNum": 0,
          "createTime": 1744858514515,
          "taskInfo": {
            "type": "m2v_img2video_hq",
            "inputs": [
              {
                "name": "input",
                "inputType": "URL",
                "token": null,
                "blobStorage": null,
                "url": "https://s21-kling.klingai.com/....jpg",
                "cover": null,
                "fromWorkId": null,
                "fromUploadId": null
              }
            ],
            "arguments": [
              {
                "name": "prompt",
                "value": "A person dancing"
              },
              {
                "name": "negative_prompt",
                "value": ""
              },
              {
                "name": "duration",
                "value": "5"
              },
              {
                "name": "kling_version",
                "value": "2.0"
              }
            ],
            "extraArgs": {},
            "callbackPayloads": [],
            "scene": "NORMAL_CREATION"
          },
          "selfAttitude": "unknown",
          "selfComment": {
            "rate": 0,
            "tags": [],
            "content": "",
            "prompts": []
          },
          "favored": false,
          "starred": false,
          "publishStatus": "unpublished",
          "deleted": false,
          "publishTime": 0,
          "submitTime": 1744858514515,
          "lipSyncStatus": 99,
          "downloadInfo": {
            "fileTypes": [
              {
                "type": "MP4",
                "watermark": true
              }
            ]
          },
          "allowPublish": true
        }
      ],
      "task": {
        "id": 123456789,
        "userId": 12345,
        "type": "m2v_img2video_hq",
        "scene": "NORMAL_CREATION",
        "status": 99,
        "status_name": "succeed",
        "status_final": true          
        "taskInfo": {
          "type": "m2v_img2video_hq",
          "inputs": [
            {
              "name": "input",
              "inputType": "URL",
              "token": null,
              "blobStorage": null,
              "url": "https://s21-kling.klingai.com/....jpg",
              "cover": null,
              "fromWorkId": null,
              "fromUploadId": null
            }
          ],
          "arguments": [
            {
              "name": "prompt",
              "value": "A person dancing"
            },
            {
              "name": "negative_prompt",
              "value": ""
            },
            {
              "name": "duration",
              "value": "5"
            },
            {
              "name": "kling_version",
              "value": "2.0"
            }
          ],
          "extraArgs": {},
          "callbackPayloads": [],
          "scene": "NORMAL_CREATION"
        },
        "favored": false,
        "deleted": false,
        "viewed": true,
        "createTime": 1744858514499,
        "updateTime": 1744858823172,
        "viewTime": 1744916388016
      },
      "etaTime": 0,
      "etaTimeOverSla": false,
      "queuingEtaTime": 0,
      "originEtaTime": 0,
      "originQueuingEtaTime": 0,
      "currentTimestamp": 1744955215247
    }
  ],
  "userPoints": {
    "total": 190500
  },
  "userTickets": {
    "ticket": [
      {
        "orderId": "123456789",
        "type": "priority",
        "packageType": "reward",
        "amount": 1,
        "balance": 1,
        "startTime": 1744046060883,
        "endTime": 1746724460883
      }
    ]
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "createdAfter and createdBefore cannot be used together"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

List of known `status` values:

| status | status_name | status_final  | Notes                                          |
|--------|-------------|---------------|------------------------------------------------|
| 5      | submitted   | false         |                                                |
| 6      | failed      | true          | Change the input prompt and try again          |
| 7      | failed      | true          | The input prompt contains sensitive words      |
| 9      | failed      | true          | Change the input prompt and try again          |
| 10     | processing  | false         |                                                |
| 50     | failed      | true          | Change the input prompt and try again          |
| 53     | failed      | true          | Your account does not support this feature     |
| 54     | failed      | true          | The queue for the free plan is busy now        |
| 58     | failed      | true          | The queue for your plan is busy now. Wait until running tasks are completed and retry, or upgrade your plan. |
| 99     | succeed     | true          |                                                |

To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response.

```typescript
{ // TypeScript, all fields are optional
    history: {
        works: {
            workId: number
            workItemId: number
            taskId: number
            userId: number
            type: string
            status: number
            status_name: string
            status_final: boolean    
            contentType: string
            resource: {
                resource: string
                height: number
                width: number
                duration: number
                resourceKey: string
            }
            cover: {
                resource: string
                height: number
                width: number
                duration: number
                resourceKey: string
            }
            starNum: number
            cloneCount: number
            reportNum: number
            createTime: number
            taskInfo: {
                type: string
                inputs: {
                    name: string
                    inputType: string
                    token: string | null
                    blobStorage: string | null
                    url: string
                    cover: string | null
                    fromWorkId: number | null
                    fromUploadId: number | null
                }[]
                arguments: {
                    name: string
                    value: string
                }[]
                extraArgs: Record<string, any>
                callbackPayloads: any[]
                scene: string
            }
            selfAttitude: string
            selfComment: {
                rate: number
                tags: any[]
                content: string
                prompts: any[]
            }
            favored: boolean
            starred: boolean
            publishStatus: string
            deleted: boolean
            publishTime: number
            submitTime: number
            lipSyncStatus: number
            downloadInfo: {
                fileTypes: {
                    type: string
                    watermark: boolean
                }[]
            }
            allowPublish: boolean
        }[]
        task: {
            id: number
            userId: number
            type: string
            scene: string
            status: number
            status_name: string
            status_final: boolean    
            taskInfo: {
                type: string
                inputs: {
                    name: string
                    inputType: string
                    token: string | null
                    blobStorage: string | null
                    url: string
                    cover: string | null
                    fromWorkId: number | null
                    fromUploadId: number | null
                }[]
                arguments: {
                    name: string
                    value: string
                }[]
                extraArgs: Record<string, any>
                callbackPayloads: any[]
                scene: string
            }
            favored: boolean
            deleted: boolean
            viewed: boolean
            createTime: number
            updateTime: number
            viewTime: number
        }
        etaTime: number
        etaTimeOverSla: boolean
        queuingEtaTime: number
        originEtaTime: number
        originQueuingEtaTime: number
        currentTimestamp: number
    }[]
    userPoints: {
        total: number
    }
    userTickets: {
        ticket: {
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }[]
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/tasks/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/tasks/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/tasks/?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-tts-voices ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tts-voices
## Retrieve available TTS voices
<small>April 18, 2025</small>

---

This endpoint retrieves a list of available text-to-speech voices from Kling.
> **https://api.useapi.net/v1/kling/tts/voices?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

**200**
**200 OK**
```json
{
  "ttsList": [
    {
      "name": "Voice Name 1",
      "speakerId": "voice_id_1",
      "exampleUrl": "https://s21-kling.klingai.com/....mp3",
      "new": false,
      "emotions": [
        {
          "name": "Happy",
          "key": "happy",
          "enable": true
        },
        {
          "name": "Sad",
          "key": "sad",
          "enable": true
        }
      ]
    },
    {
      "name": "Voice Name 2",
      "speakerId": "voice_id_2",
      "exampleUrl": "https://s21-kling.klingai.com/....mp3",
      "new": true,
      "emotions": []
    }
  ],
  "lastSpeakerId": "voice_id_1",
  "typeList": ["en", "zh"]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  ttsList: {
    name: string
    speakerId: string
    exampleUrl: string
    new: boolean
    emotions: {
      name: string
      key: string
      enable: boolean
    }[]
  }[]
  lastSpeakerId: string
  typeList: string[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/tts/voices?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/tts/voices?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/tts/voices?email={email}"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-effects ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-effects
## Get Available Video Effects
<small>April 18, 2025 (July 25, 2025)</small>

---

This endpoint retrieves a list of available special effects that can be applied to videos when using the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint.
> **https://api.useapi.net/v1/kling/videos/effects/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

**200**
**200 OK**
```json
[
  {
    "name": "rocket",
    "caption": "RocketRocket",
    "hot": true,
    "minimalKrnVersion": 20250416,
    "supportedModelMode": ["std", "pro"],
    "compositedSchema": {
      "preprocess": {
        "taskType": "",
        "taskVersion": "",
        "defaultPrompt": "",
        "requireInputs": [
          {
            "inputType": "URL",
            "contentType": "IMAGE",
            "optional": false,
            "contentName": "image"
          }
        ]
      },
      "process": {
        "taskType": "m2v_img2video_se_hq",
        "taskVersion": "1.6",
        "defaultPrompt": "emits dazzling white smoke and orange Mach rings from the bottom, and it begins to rise into the air...",
        "requireInputs": [
          {
            "inputType": "URL",
            "contentType": "IMAGE",
            "optional": false,
            "contentName": "image"
          }
        ]
      }
    },
    "videoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-视频.gif",
    "coverUrl": "https://s21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-封面.jpg",
    "webVideoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-视频.mp4",
    "effectSupported": true,
    "promptSupported": true
  },
  {
    "name": "spinoff",
    "caption": "DizzyDizzy",
    "hot": false,
    "minimalKrnVersion": 400,
    "supportedModelMode": ["pro"],
    "videoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-视频.gif",
    "coverUrl": "https://s21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-封面.png",
    "webVideoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-视频-compress.mp4",
    "effectSupported": false,
    "promptSupported": false
  }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

The response contains an array of available effects that can be used with the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint.

Each effect now includes additional flags:
- `effectSupported`: Indicates if the effect is supported by the current endpoint (false means it requires image preprocessing)
- `promptSupported`: Indicates if the effect accepts custom prompts (false means it uses only default prompts)

##### Model 
```typescript
{ // TypeScript, all fields are optional
  name: string          // Effect name identifier (used in requests)
  caption: string       // Display name for the effect
  hot: boolean          // Whether this is a featured effect
  minimalKrnVersion?: number // Minimum kernel version required
  supportedModelMode?: string[] // Supported model modes ("std", "pro")
  effectSupported?: boolean // Whether effect is supported (false = requires preprocessing)
  promptSupported?: boolean // Whether effect accepts custom prompts
  compositedSchema?: {  // Legacy schema information
    preprocess?: {
      taskType: string
      taskVersion: string
      defaultPrompt: string
      requireInputs: Array<{
        inputType: string
        contentType: string
        optional: boolean
        contentName: string
      }>
    }
    process?: {
      taskType: string
      taskVersion: string
      defaultPrompt: string
      requireInputs: Array<{
        inputType: string
        contentType: string
        optional: boolean
        contentName: string
      }>
    }
  }
  videoUrl: string      // Preview video URL for the effect
  coverUrl: string      // Cover image URL for the effect
  webVideoUrl: string   // Web-optimized preview video URL
}
```

##### Usage Notes
- **effectSupported**: Only effects with `effectSupported: true` can be used with the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint
- **promptSupported**: Effects with `promptSupported: true` accept custom prompts; others use built-in defaults
- **supportedModelMode**: Check which quality modes (std/pro) are available for each effect
- Use the effect's `name` value when making requests to the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint

##### Examples

**Curl**
``` bash
curl -X GET "https://api.useapi.net/v1/kling/videos/effects?email=user@example.com" \
   -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/effects"; 
const response = await fetch(`${apiUrl}?email=${email}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`,
  }
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/effects"
headers = {
    "Authorization" : f"Bearer {token}"
}
params = {
    "email": email
}
response = requests.get(apiUrl, headers=headers, params=params)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-motions ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-motions
## Get Available Motions
<small>October 7, 2025 (January 6, 2026)</small>

---

This endpoint retrieves a list of available motion assets. Official motion videos can be used as `motionUrl` in [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create). Uses Kling v2.6 modality asset API.
> **https://api.useapi.net/v1/kling/videos/motions?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `mine` is optional, boolean value.
  When `true`, retrieves user's own motion assets.
  When `false` or omitted, retrieves official Kling motion templates.

**Notes:**
- Use the `url` field as `motionUrl` when making requests to motion-create
- Official motions are pre-processed motion videos provided by Kling
- User motions are videos previously uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) - use `resourceUrl` from upload response

##### Responses

**200**
**200 OK**

```json
[
  {
    "assetId": "motion_12345",
    "assetType": "MOTION",
    "url": "https://v15-kling.klingai.com/bs2/upload-ylab-stunt-sgp/.../motion.mp4",
    "coverUrl": "https://s15-kling.klingai.com/.../cover.jpg",
    "duration": 5760,
    "width": 720,
    "height": 1280,
    "hasAudio": true,
    "createTime": 1767669665000
  }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
Array<{ // TypeScript, all fields are optional
  assetId: string        // Unique asset identifier
  assetType: string      // "MOTION"
  url: string            // URL to the motion video - use as motionUrl in motion-create
  coverUrl?: string      // URL to the cover/thumbnail image
  duration?: number      // Duration in milliseconds
  width?: number         // Video width in pixels
  height?: number        // Video height in pixels
  hasAudio?: boolean     // Whether the motion has audio
  createTime?: number    // Creation timestamp
}>
```

##### Examples

**Curl**
``` bash
# Get official motions
curl -X GET "https://api.useapi.net/v1/kling/videos/motions?email=user@example.com" \
   -H "Authorization: Bearer ..."

# Get user motions
curl -X GET "https://api.useapi.net/v1/kling/videos/motions?email=user@example.com&mine=true" \
   -H "Authorization: Bearer ..."
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const mine = false; // false for official, true for user
const apiUrl = "https://api.useapi.net/v1/kling/videos/motions";
const response = await fetch(`${apiUrl}?email=${email}&mine=${mine}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`,
  }
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/motions"
headers = {
    "Authorization" : f"Bearer {token}"
}
params = {
    "email": email,
    "mine": False  # False for official, True for user
}
response = requests.get(apiUrl, headers=headers, params=params)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts
## Create/update Kling API account
<small>April 18, 2025 (Jun 19, 2025)</small>

---

This endpoint adds or updates a Kling account in your configuration. The API will automatically login to verify your credentials.
> **https://api.useapi.net/v1/kling/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "password": "your-password",
  "maxJobs": 50
}
```

- `email` and `password` are **required**.   
  Please see [Setup Kling](/docs/start-here/setup-kling) for details.  
  
- `maxJobs` is **required**, specify maximum number of concurrent jobs (`1`-`50`)

##### Responses 

**201**
**201 Created**
```json
{
  "email": "user@example.com",
  "session": {
    "userId": "user12345",
    "ExpireTime": 123456789,
    "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
  },
  "maxJobs": 50,
  "password": "…secured…"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Account does not exist or password is incorrect"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**402**
**402 Payment Required**
```json
{
  "error": "Subscription required",
  "code": 402
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string
  session: {
    userId: string
    ExpireTime: number
    ExpireTimeUTC: string
  }
  maxJobs: number
  password: string
  error: string
}
```

##### Examples

**Curl**
``` bash
curl -X POST https://api.useapi.net/v1/kling/accounts \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{"email": "user@example.com", "password": "your-password", "maxJobs": 50}'
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/kling/accounts"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: "user@example.com",
    password: "your-password",
    maxJobs: 50
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/kling/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": "user@example.com",
    "password": "your-password",
    "maxJobs": 50
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-assets ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-assets
## Upload asset to Kling
<small>April 18, 2025 (April 28, 2026)</small>

---

This endpoint uploads an asset to your Kling account for later use in image and video generation.
> **https://api.useapi.net/v1/kling/assets/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.
- `Content-Type` is **required**, select from the table below:

| Content-Type        | File Extension | Max Size | Notes |
| ------------------- | -------------- | -------- | ----- |
| image/png           | png            | 10MB     | Minimum dimensions of 300px |
| image/jpeg          | jpg/jpeg       | 10MB     | Minimum dimensions of 300px |
| video/mp4           | mp4            | 150MB    | 720p/1080p resolution, 10s max |
| video/quicktime     | mov            | 150MB    | 720p/1080p resolution, 10s max |
| audio/wav           | wav            | 30MB     | 30 seconds max |
| audio/wave          | wav            | 30MB     | 30 seconds max |
| audio/mpeg          | mp3            | 30MB     | 30 seconds max |
| audio/mp4           | m4a            | 30MB     | 30 seconds max |
| audio/flac          | flac           | 30MB     | 30 seconds max |
| audio/aac           | aac            | 30MB     | 30 seconds max |
| audio/ogg           | ogg            | 30MB     | 30 seconds max |

##### Query Parameters

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

**200**
**200 OK**
```json
{
  "status": 3,
  "url": "https://s21-kling.klingai.com/....jpg",
  "message": "",
  "fileName": "abc123def456789.jpg"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Content-Type {content-type} is not supported. Valid values: image/png,image/jpeg,video/mp4,video/quicktime,audio/wav,audio/wave,audio/mpeg,audio/mp4,audio/flac,audio/aac,audio/ogg"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

You can retrieve uploaded asset details via [GET assets/uploaded/?fileName=`fileName`](/docs/api-kling-v1/get-kling-assets-uploaded).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    status: number    // 3 = success for image, 1 = success for video
    url: string       // URL of the uploaded asset for image/audio
    message: string   // Status message or error
    error: string
    fileName?: string // Generated unique filename
    resourceUrl?: string  // URL of the processed file (video)
    coverUrl?: string     // URL of the cover image (video)
    cover?: {
        resource: string   // URL of the cover
        height: number     // Height in pixels
        width: number      // Width in pixels
        duration: number   // Duration in milliseconds (for video)
        resourceKey: string // Resource key
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: image/jpeg" \
  --data-binary @/path/to/your/image.jpg
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = `https://api.useapi.net/v1/kling/assets/?email=${email}`; 
let blob;
/*
    // Example 1: Fetch image from URL
    const imageUrl = "https://example.com/image.jpg";
    const responseImage = await fetch(imageUrl);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load image from local file (Node.js)
    const fsp = require('fs').promises;
    const imageFileName = "./image.jpg";
    blob = new Blob([await fsp.readFile(imageFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="image-file" type="file"> 
    const imageFile = document.getElementById(`image-file`);
    if (imageFile.files[0])
        blob = imageFile.files[0];
*/
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "image/jpeg"
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v1/kling/assets/?email={email}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

# Example: Load image from local file
image_file_path = "./image.jpg"
with open(image_file_path, 'rb') as image_file:
    file_content = image_file.read()

response = requests.post(apiUrl, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars-video ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars-video
## Generate avatar video
<small>January 12, 2026</small>

---

This endpoint generates a lip-sync video from an avatar image and audio. The avatar speaks with realistic lip movements synchronized to the provided audio or generated text-to-speech.

You can use either:
- A saved avatar from [POST /avatars](/docs/api-kling-v1/post-kling-avatars) or system templates
- A direct image URL

For audio, you can provide either:
- A pre-recorded audio file URL (upload via [POST /assets](/docs/api-kling-v1/post-kling-assets))
- Text that will be converted to speech using TTS
> **https://api.useapi.net/v1/kling/avatars/video**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "avatarId": "123456789012",
  "text": "Hello, welcome to our product demo!",
  "speakerId": "speaker_id_123"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

###### Avatar Source (one required)

Provide either `avatarId` or `imageUrl`, not both:

- `avatarId` is the ID of a saved avatar.
  Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to list your personal avatars or browse system templates.
  When using an avatar, its saved `prompt` and TTS settings are used as defaults.

- `imageUrl` is a direct URL to an avatar image.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

###### Audio Source (one required)

Provide either `audioUrl` or `text`, not both:

- `audioUrl` is a URL to a pre-recorded audio file.
  You can upload audio using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

- `text` is the text to be converted to speech.
  Maximum length: 5000 characters.
  Requires `speakerId` to be provided.

###### TTS Options (when using text)

These options apply when providing `text` for text-to-speech:

- `speakerId` is **required** when using `text`.
  Use [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) to get available speaker IDs.
  If using an `avatarId`, the avatar's saved `ttsSpeaker` is used as default.

- `speed` is optional, speech speed.
  Range: `0.8` to `2.0`. Default: `1`.
  If using an `avatarId`, the avatar's saved `ttsSpeed` is used as default.

- `emotion` is optional, speech emotion.
  Supported values: `neutral` (default), `happy`, `angry`, `sad`, `fearful`, `disgusted`, `surprised`.
  Not all emotions are available for all speakers. Check [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) for each speaker's supported emotions.
  If using an `avatarId`, the avatar's saved `ttsEmotionKey` is used as default.

###### Video Options

- `prompt` is optional, description of the avatar's behavior/appearance.
  Maximum length: 2000 characters.
  If using an `avatarId`, the avatar's saved `prompt` is used as default.
  Default: "Natural speaking".

- `mode` is optional, the video generation mode.
  Supported values: `std` (default), `pro`.

###### Scheduler Parameters

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2digital",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_img2digital",
      "inputs": [
        {
          "name": "image",
          "inputType": "URL",
          "url": "https://s21-kling.klingai.com/ai-platform/.../avatar.jpg"
        },
        {
          "name": "audio",
          "inputType": "URL",
          "url": "https://s21-kling.klingai.com/ai-platform/.../audio.mp3"
        }
      ],
      "arguments": [
        { "name": "prompt", "value": "Natural speaking" },
        { "name": "upload_method", "value": "MY_AVATAR" },
        { "name": "duration", "value": "5.234" },
        { "name": "model_mode", "value": "std" }
      ]
    },
    "createTime": 1736640000000,
    "updateTime": 1736640000000
  },
  "status": 5,
  "status_name": "submitted",
  "status_final": false
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  task: {
    id: number
    userId: number
    type: string
    scene: string
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    taskInfo: {
      type: string
      inputs: { name: string, inputType: string, url: string }[]
      arguments: { name: string, value: string }[]
    }
    createTime: number
    updateTime: number
  }
  works: object[]
  status: number
  status_name: string
  status_final: boolean
  message: string
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/avatars/video" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "avatarId": "123456789012",
     "text": "Welcome to our demo!",
     "speakerId": "speaker_id_123"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/avatars/video";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    avatarId: "123456789012",
    text: "Welcome to our demo!",
    speakerId: "speaker_id_123"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/avatars/video"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "avatarId": "123456789012",
    "text": "Welcome to our demo!",
    "speakerId": "speaker_id_123"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars
## Create avatar
<small>January 12, 2026</small>

---

This endpoint creates a new avatar from an image. Avatars are digital characters that can be animated with lip-sync using [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video).

Most fields are optional and will be automatically populated using AI if not provided. The AI analyzes your image to suggest an appropriate nickname, description, scene, and TTS settings.
> **https://api.useapi.net/v1/kling/avatars**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `imageUrl` is **required**, the URL of the avatar image.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

###### Optional Parameters (AI Auto-Populated)

The following fields will be automatically filled by AI if not provided:

- `nickname` is optional, display name for the avatar.
  Maximum length: 30 characters.

- `prompt` is optional, description/prompt for the avatar.
  Maximum length: 2000 characters.
  Used as the default prompt when generating avatar videos.

- `scene` is optional, the avatar's use case category.
  Supported values: `all`, `social_media`, `entertainment`, `advertising_marketing` (default), `business`, `education`, `virtual_idol`.

- `ttsSpeaker` is optional, the TTS speaker ID for voice.
  Use [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) to get available speaker IDs.
  AI will recommend an appropriate voice if not provided.

- `ttsSpeed` is optional, speech speed.
  Range: `0.8` to `2.0`. Default: `1`.

- `ttsEmotionKey` is optional, speech emotion.
  Supported values: `neutral` (default), `happy`, `angry`, `sad`, `fearful`, `disgusted`, `surprised`.
  Note: Not all emotions are available for all speakers. Check [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) for each speaker's supported emotions.

##### Responses

**200**
**200 OK**
```json
{
  "id": "300137233318846",
  "status": "SUCCESS"
}
```

Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to retrieve the full avatar details after creation.

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript
  id: string
  status: 'SUCCESS' | 'FAILED'
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/avatars" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/avatars";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    imageUrl: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/avatars"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-elements
## Create element
<small>January 12, 2026 (March 6, 2026)</small>

---

This endpoint creates one or more elements from a cover image or video. Elements are saved character/object references that can be reused across multiple generations in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) using the `@element_N` syntax.

There are two element types:
- **IMAGE** elements: Created from a `coverImage`, with optional multi-angle views
- **VIDEO** elements: Created from a `video` URL (mp4, minimum 3 seconds, auto-trimmed to 8s), with optional voice assignment. VIDEO elements can only be used in v3 video generation via [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni).

| Feature | IMAGE | VIDEO |
|---------|:-----:|:-----:|
| Input | `coverImage` | `video` (mp4, min 3s, auto-trimmed to 8s) |
| `voice` support | ✅ (character tag only) | ✅ (character tag only) |
| Auto voice extraction | ❌ | ✅ (character tag, 5-60s video) |
| Custom voice from URL | ✅ (mp4, 5-60s) | ✅ (mp4, 5-60s) |
| `extraImage1/2/3` | ✅ | ❌ |
| `generateViews` | ✅ | ❌ |
| Used in O1 omni | ✅ | ❌ |
| Used in v3 omni | ✅ | ✅ |

The `generateViews` option (IMAGE only) uses AI to create multiple variations of your element with different angles, which can produce up to 3 separate elements from a single image. You can review the results and delete ones you don't like using [DELETE /elements/`elementId`](/docs/api-kling-v1/del-kling-elements-elementId).
> **https://api.useapi.net/v1/kling/elements**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "name": "MyCharacter",
  "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
  "tag": "character"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `name` is **required**, the base name for the element.
  Maximum length: 15 characters.
  A 5-character random suffix is automatically appended (e.g., "MyChar" becomes "MyChar ABC12").

- `coverImage` is required for IMAGE elements, the URL of the primary image.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.
  Cannot be used together with `video`.

- `video` is required for VIDEO elements, the URL of a video (mp4 format, minimum 3 seconds).
  You can upload videos using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.
  The video is preprocessed to extract a cover frame and normalized video. Videos longer than 8 seconds are automatically trimmed.
  Minimum 700px shortest edge.
  Cannot be used together with `coverImage`.

- `voice` is optional (`character` tag required), the voice to assign to the element.
  Accepts an official voice name/ID from [GET /elements/voices](/docs/api-kling-v1/get-kling-elements-voices), or a video URL (mp4, 5-60 seconds) to extract a custom voice from.
  For VIDEO elements without an explicit voice, voice extraction is automatically attempted from the video (requires 5-60 seconds with audio; silently skipped if video is too short).
  Voice is only supported for elements with the `character` tag.

- `description` is optional, a text description of the element.
  Maximum length: 100 characters.
  If not provided, a description is automatically generated from the image using AI.

- `tag` is optional, the category tag for the element.
  Use [GET /elements/tags](/docs/api-kling-v1/get-kling-elements-tags) to get available tags.
  Accepts either `id` or `tagKey` (e.g., "1" or "character").
  If not provided, the tag is automatically detected from the image using AI.

###### Secondary Images (IMAGE only)

You can optionally provide additional angle/view images:

- `extraImage1` is optional, URL of first additional view.
- `extraImage2` is optional, URL of second additional view.
- `extraImage3` is optional, URL of third additional view.

Maximum 3 secondary images allowed.
Cannot be used together with `generateViews` or `video`.

###### Auto-Generate Views (IMAGE only)

- `generateViews` is optional, set to `true` to have AI generate 3 multi-angle variations.
  When enabled, the system generates different views of your element automatically.
  This can create **up to 3 separate elements**, one for each variation group.
  Cannot be used together with `extraImage1/2/3` or `video`.
  This call can take up to 60 seconds to complete since generation takes time.

##### Responses

**200**
**200 OK**

**Standard response (without generateViews):**
```json
{
  "elements": [
    {
      "id": "u_123456789012345",
      "name": "MyCharacter ABC12",
      "userId": 12345678,
      "description": "AI-generated description of the character",
      "cover": {
        "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
        "width": 768,
        "height": 1365,
        "resourceKey": "cover",
        "cover": true,
        "slotKey": ""
      },
      "resources": [
        {
          "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
          "width": 768,
          "height": 1365,
          "resourceKey": "cover",
          "cover": true,
          "slotKey": ""
        }
      ],
      "tagList": [],
      "createTime": 1736640000000,
      "updateTime": 1736640000000,
      "favored": false,
      "official": false
    }
  ],
  "count": 1
}
```

**Response with generateViews (creates up to 3 separate elements, each with 4 views):**
```json
{
  "elements": [
    {
      "id": "u_123456789012345",
      "name": "MyCharacter ABC12",
      "userId": 12345678,
      "description": "AI-generated description",
      "cover": {
        "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
        "resourceKey": "cover",
        "cover": true,
        "slotKey": ""
      },
      "resources": [
        { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
        { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" },
        { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" },
        { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" }
      ],
      "tagList": []
    },
    {
      "id": "u_234567890123456",
      "name": "MyCharacter DEF34",
      "description": "AI-generated description",
      "resources": [
        { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
        { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" },
        { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" },
        { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" }
      ],
      "tagList": []
    }
  ],
  "count": 2
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  elements: {
    id: string
    name: string
    userId: number
    type: 'IMAGE' | 'VIDEO'
    description: string
    cover: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
    }
    resources: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
      voice: {
        id: number
        name: string
        official: boolean
        resource: object
      }
    }[]
    tagList: object[]
    voice: {
      id: number
      name: string
      official: boolean
      resource: object
    }
    currentVersion: number
    createTime: number
    updateTime: number
    favored: boolean
    official: boolean
  }[]
  count: number
}
```

##### Usage After Creation

Once created, you can use element IDs in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni), [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni), and [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create):

```json
{
  "prompt": "Character @element_1 walking through a beautiful garden",
  "element_1": "u_123456789012345"
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/elements" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "name": "FashionLady",
     "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
     "tag": "character"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/elements";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    name: "FashionLady",
    coverImage: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
    tag: "character"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/elements"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "name": "FashionLady",
    "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
    "tag": "character"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors-elements
## Generate Images with KOLORS Elements
<small>July 18, 2025 (October 31, 2025)</small>

---

This endpoint generates images using Kling's KOLORS v2.1 with multiple image elements (up to 4 subject images, plus optional scene and style images) that will appear as elements in the generated image. This allows for more complex compositions with multiple reference images.
> **https://api.useapi.net/v1/kling/images/kolors-elements**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A digital art gallery with modern paintings and sculptures on display",
  "subjectImage1": "https://example.com/painting1.jpg",
  "subjectImage2": "https://example.com/sculpture1.jpg",
  "subjectImage3": "https://example.com/painting2.jpg",
  "subjectImage4": "https://example.com/decoration.jpg",
  "sceneImage": "https://example.com/gallery-background.jpg",
  "styleImage": "https://example.com/art-style.jpg",
  "aspect_ratio": "16:9",
  "imageCount": 1,
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `prompt` is optional, the text description of the image to generate.    
  Maximum length: 2500 characters.
  
- `subjectImage1`, `subjectImage2`, `subjectImage3` and `subjectImage4` are optional URLs to subject images that will appear as elements in the generated image.    
  Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `sceneImage` is optional, URL to a scene/background image.     
  Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `styleImage` is optional, URL to a style reference image.  
  Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `aspect_ratio` is optional, the aspect ratio of the generated image.     
  Supported values: `1:1`, `16:9` (default), `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`.
  
- `imageCount` is optional, the number of images to generate.   
  Range: `1` to `9`. Default: `1`.
  
- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Note:** At least two images must be provided (any combination of subjectImage1-4, sceneImage, or styleImage).

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "mmu_multi_img2img_aiweb",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "mmu_multi_img2img_aiweb",
      "inputs": [
        {
          "name": "subject_image_0",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/painting1.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "raw_subject_image_0",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/painting1.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "subject_image_1",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/sculpture1.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "scene_image",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/gallery-background.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A digital art gallery with modern paintings and sculptures on display"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        },
        {
          "name": "imageCount",
          "value": "1"
        },
        {
          "name": "kolors_version",
          "value": "2.1"
        },
        {
          "name": "img_resolution",
          "value": "1k"
        },
        {
          "name": "style",
          "value": "默认"
        },
        {
          "name": "imageList",
          "value": "[{\"top\":0,\"left\":0,\"width\":1,\"height\":1},{\"top\":0,\"left\":0,\"width\":1,\"height\":1}]"
        },
        {
          "name": "biz",
          "value": "klingai"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "mmu_multi_img2img_aiweb",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "At least two images must be provided"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/images/kolors-elements" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "prompt": "A digital art gallery with modern paintings and sculptures on display",
     "subjectImage1": "https://example.com/painting1.jpg",
     "subjectImage2": "https://example.com/sculpture1.jpg",
     "sceneImage": "https://example.com/gallery-background.jpg"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/kolors-elements"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "A digital art gallery with modern paintings and sculptures on display",
    subjectImage1: "https://example.com/painting1.jpg",
    subjectImage2: "https://example.com/sculpture1.jpg",
    sceneImage: "https://example.com/gallery-background.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/kolors-elements"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "A digital art gallery with modern paintings and sculptures on display",
    "subjectImage1": "https://example.com/painting1.jpg",
    "subjectImage2": "https://example.com/sculpture1.jpg",
    "sceneImage": "https://example.com/gallery-background.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors
## Generate Images with KOLORS
<small>April 24, 2025 (February 9, 2026)</small>

---

This endpoint generates images using Kling's KOLORS. It supports KOLORS v3.0 for text-to-image with reference images, and KOLORS v2.1 for text-to-image with face, subject, and restyle reference workflows.

**Note:** KOLORS v2.0 and v1.5 have been retired by Kling from the website. Their features (restyle, face, subject) are now available under v2.1. The legacy versions are still accepted for backwards compatibility.

##### Model Support Matrix

| Feature | v3.0 | v2.1 |
|---------|:----:|:----:|
| Text-to-image | ✅ | ✅ |
| Reference images (`image_1`-`image_10`) | ✅ (up to 10) | ❌ |
| Face reference (`reference: face`) | ❌ | ✅ |
| Subject reference (`reference: subject`) | ❌ | ✅ |
| Restyle (`reference: restyle`) | ❌ | ✅ |
| `resolution` | `1k`, `2k` (default) | `1k`, `2k` (default, text-to-image only) |
| `aspect_ratio` default | `16:9` | `16:9` |
| `imageCount` default | `2` | `1` |
| `aspect_ratio: auto` | ✅ (with images only) | ❌ |
> **https://api.useapi.net/v1/kling/images/kolors**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A woman @image_1 dancing elegantly in a ballroom",
  "version": "kling-v3-0",
  "resolution": "2k",
  "aspect_ratio": "3:4",
  "imageCount": 2,
  "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `prompt` is **required**, the text description of the image to generate.
  Maximum length: 2500 characters.
  For v3, use `@image_1`, `@image_2`, etc. to reference images in your prompt.

- `version` is optional, the KOLORS model version to use.
  Supported values: `kling-v3-0` (default), `kling-v2-1`.
  Legacy (retired): `kling-v1-5`, `kling-v1-6`, `kling-v2-0` — still accepted for backwards compatibility.

- `resolution` is optional, the resolution of the generated image.
  Supported values: `1k`, `2k` (default). Only available for v3.0 and v2.1 text-to-image (`reference: none`). Not supported by subject/face/restyle.

###### v3 Parameters

- `image_1` through `image_10` are optional (v3 only), URLs of reference images.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets).
  Reference in prompt using `@image_1`, `@image_2`, etc.

**Note:** v3 does not support `reference`, `imageReference`, `faceStrength`, `subjectStrength`, or `faceNo` parameters.

###### v3 Aspect Ratios

When using `version: kling-v3-0`, the supported aspect ratios are:
`9:16`, `2:3`, `3:4`, `1:1`, `4:3`, `3:2`, `16:9` (default), `21:9`, `auto` (with images only).

###### v2.1 Reference Parameters

- `reference` is optional, the type of reference to use (v2.1).
  Supported values:
  - `none` (default) — text-to-image
  - `subject` — subject similarity reference
  - `face` — face similarity reference
  - `restyle` — style transfer from reference image

- `imageReference` is required if `reference` is not `none`, the URL of the reference image.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

- `aspect_ratio` is optional, the aspect ratio of the generated image. Not supported by `restyle` reference type.
  Supported values: `1:1`, `16:9` (default), `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`.

- `imageCount` is optional, the number of images to generate.
  Range: `1` to `9`. Default: `1` (v3 default: `2`).

- `faceStrength` is optional, the strength of face similarity for both `face` and `subject` reference types.
  Range: `1` to `100`. Default: `65`.

- `subjectStrength` is optional, the strength of subject similarity for `subject` reference type.
  Range: `1` to `100`. Default: `50`.

- `faceNo` is optional, the index of the face to use in multi-face images for `face` reference type.
  Default: `1`. You can use [POST /images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces) to detect faces in an image.

###### Scheduler Parameters

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "mmu_img2img_aiweb",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "mmu_img2img_aiweb",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/face.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "feature",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/....jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "Portrait of a woman with blue eyes, detailed, photorealistic"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        },
        {
          "name": "imageCount",
          "value": "1"
        },
        {
          "name": "kolors_version",
          "value": "2.1"
        },
        {
          "name": "fidelity",
          "value": "0.65"
        },
        {
          "name": "style",
          "value": "默认"
        },
        {
          "name": "faceBound",
          "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}"
        },
        {
          "name": "referenceType",
          "value": "mmu_img2img_aiweb_v15_character"
        },
        {
          "name": "biz",
          "value": "klingai"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [
        {
          "name": "face_count",
          "value": "1"
        },
        {
          "name": "referenceImageWidth",
          "value": "724"
        },
        {
          "name": "referenceImageHeight",
          "value": "1268"
        }
      ],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "mmu_img2img_aiweb",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "reference \"face\" does not support subjectStrength"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/images/kolors" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "prompt": "Portrait of a woman with blue eyes, detailed, photorealistic",
     "reference": "face",
     "imageReference": "https://example.com/face.jpg",
     "faceStrength": 65,
     "faceNo": 1
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/kolors"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "Portrait of a woman with blue eyes, detailed, photorealistic",
    reference: "face",
    imageReference: "https://example.com/face.jpg",
    faceStrength: 65,
    faceNo: 1
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/kolors"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "Portrait of a woman with blue eyes, detailed, photorealistic",
    "reference": "face",
    "imageReference": "https://example.com/face.jpg",
    "faceStrength": 65,
    "faceNo": 1
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-omni ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-omni
## Generate Images with Omni
<small>December 10, 2025 (March 19, 2026)</small>

---

This endpoint generates images using Kling's Omni model (`O1` and `v3`). It supports text-to-image generation with up to 10 reference images and/or saved elements that can be referenced in your prompt.

##### Version Comparison

| Feature | v3 | O1 |
|---------|:--:|:--:|
| Resolution | `1k`, `2k`, `4k` (VIP) | `1k`, `2k` |
| Default `aspect_ratio` | `auto` | `16:9` |
| `auto` aspect ratio | ✅ | ❌ |
| `story_mode` (Series Mode) | ✅ | ❌ |
> **https://api.useapi.net/v1/kling/images/omni**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A woman @image_1 dancing elegantly in a ballroom",
  "resolution": "2k",
  "aspect_ratio": "16:9",
  "imageCount": 2,
  "story_mode": true,
  "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required**, the text description of the image to generate.
  Maximum length: 1700 characters.
  Use `@image_1`, `@image_2`, etc. to reference images in your prompt.
  Use `@element_1`, `@element_2`, etc. (or `@object_1`, etc.) to reference saved elements.

- `omni_version` is optional, the Omni model version to use.
  Supported values: `o1`, `v3` (default).

- `resolution` is optional, the resolution of the generated image.
  Supported values: `1k` (default), `2k`, `4k` (v3 only, **VIP required**).

- `aspect_ratio` is optional, the aspect ratio of the generated image.
  Supported values: `auto` (v3 only), `16:9` (default for O1), `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`.
  v3 defaults to `auto`. `auto` is NOT available for O1.

- `imageCount` is optional, the number of images to generate.
  Range: `1` to `9`. Default: `1`.

- `story_mode` is optional, enables Series Mode for coherent multi-image generation (v3 only).
  Requires at least one reference image or element. When enabled, generates a coherent set of images rather than independent generations.
  Default: `false`.

- `unlimited` is optional, enables unlimited generation mode for eligible Pro and above accounts (subscribed prior December 15, 2025).
  Default: `false`.

###### Reference Images

- `image_1` through `image_10` are optional, URLs of reference images.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets).
  Reference in prompt using `@image_1`, `@image_2`, etc.

###### Saved Elements

- `element_1` through `element_10` are optional, IDs of saved elements.
  Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements).
  Reference in prompt using `@element_1` or `@object_1`, etc.

**Note:** Images and elements share the same pool of 10 slots. Combined total cannot exceed 10.

###### Prompt Reference Syntax

| Input Type | Prompt Syntax | Example |
|------------|---------------|---------|
| Images | `@image_1`, `@image_2`, ... | `"A woman @image_1 in a ballroom"` |
| Elements | `@element_1` or `@object_1`, ... | `"Character @element_1 sitting..."` |

###### Scheduler Parameters

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "mmu_omni_image",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "mmu_omni_image",
      "inputs": [
        {
          "name": "image_1",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A woman Image1 dancing elegantly in a ballroom"
        },
        {
          "name": "rich_prompt",
          "value": "A woman <<<image_1>>> dancing elegantly in a ballroom"
        },
        {
          "name": "kolors_version",
          "value": "3.0-omni"
        },
        {
          "name": "img_resolution",
          "value": "2k"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        },
        {
          "name": "imageCount",
          "value": "1"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1733836800000,
    "updateTime": 1733836800000
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "mmu_omni_image",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
# Using reference image
curl -X POST "https://api.useapi.net/v1/kling/images/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "A woman @image_1 dancing elegantly in a ballroom",
     "resolution": "2k",
     "aspect_ratio": "16:9",
     "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
   }'

# Using story_mode (Series Mode) for coherent multi-image generation
curl -X POST "https://api.useapi.net/v1/kling/images/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "A series of @image_1 in different seasons",
     "resolution": "2k",
     "aspect_ratio": "16:9",
     "imageCount": 3,
     "story_mode": true,
     "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
   }'

# Using saved element
curl -X POST "https://api.useapi.net/v1/kling/images/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "Character @element_1 in a garden setting",
     "resolution": "2k",
     "aspect_ratio": "16:9",
     "element_1": "u_123456789012345"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/omni";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "Character @element_1 in a garden setting",
    resolution: "2k",
    aspect_ratio: "16:9",
    element_1: "u_123456789012345"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/omni"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "Character @element_1 in a garden setting",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "element_1": "u_123456789012345"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-recognize-faces ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-recognize-faces
## Detect Faces in Images
<small>April 24, 2025 (October 1, 2025)</small>

---

This endpoint detects faces in the provided image and returns face information, including positions and features. This is useful for identifying facial features prior to using them with [POST /images/kolors](/docs/api-kling-v1/post-kling-images-kolors) with the `face` reference type.

You can execute an unlimited number of face detections for **free**. This feature is available for all Kling subscription plans, including the free one.
> **https://api.useapi.net/v1/kling/images/recognize-faces**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "imageReference": "https://example.com/image.jpg"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `imageReference` is **required**, the URL of the image to analyze.  
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

##### Responses 

**200**
**200 OK**
```json
{
  "status": 0,
  "message": "",
  "faceItems": [
    {
      "name": "face_0",
      "resources": [
        {
          "name": "face",
          "type": "image",
          "url": "https://s21-kling.klingai.com/...face_0.jpg",
          "marginTop": 0,
          "countInRow": 1
        },
        {
          "name": "face_feature",
          "type": "image",
          "url": "https://s21-kling.klingai.com/...face_feature_0.jpg",
          "marginTop": 0,
          "countInRow": 1
        }
      ],
      "arguments": [
        {
          "name": "face_bound",
          "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}"
        }
      ]
    }
  ],
  "mediaInfo": {
    "type": "image",
    "duration": 0,
    "width": 724,
    "height": 1268
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter imageReference is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

If the response contains `faceItems`, it means faces were detected in the image. Each face is listed with its position and features. The response will include:

- `status`: 0 indicates success
- `faceItems`: An array of detected faces, each with:
  - `resources`: Face images and feature information
  - `arguments`: Contains face bounding box coordinates
- `mediaInfo`: Information about the original image

##### Model 
```typescript
{ // TypeScript, all fields are optional
  status: number  // 0 for success
  message: string // Empty string on success, error message otherwise
  error: string
  faceItems?: {
    name: string  // Face identifier (e.g., "face_0")
    resources: {
      name: string  // Resource type identifier (e.g., "face", "face_feature")
      type: string  // Resource type (typically "image")
      url: string   // URL to the resource
      marginTop: number // Display margin
      countInRow: number // Display count in row
    }[]
    arguments: {
      name: string  // Argument name (e.g., "face_bound")
      value: string // JSON string with facial bounds coordinates
    }[]
  }[]
  mediaInfo: {
    type: string  // Media type (typically "image")
    duration: number // Duration for video (0 for image)
    width: number // Image width in pixels
    height: number // Image height in pixels
  }
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/images/recognize-faces" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "imageReference": "https://example.com/image.jpg"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    imageReference: "https://example.com/image.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "imageReference": "https://example.com/image.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-upscale ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-upscale
## Upscale Images
<small>April 24, 2025 (October 1, 2025)</small>

---

This endpoint upscales previously generated images to higher resolution. It takes a task ID and work ID from a completed task, and creates a new upscaled version of the specified image.
> **https://api.useapi.net/v1/kling/images/upscale**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "task_id": "123456789",
  "workId": "987654321"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `task_id` is **required**, the ID of a completed task that generated the image.
  Must be in the `succeed` status, which can be checked using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).
  
- `workId` is **required**, the ID of the specific image from the task to upscale.
  Can be found in the `works` array of the [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) response.

- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "mmu_image_upscale_aiweb",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "mmu_image_upscale_aiweb",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/....jpg",
          "cover": null,
          "fromWorkId": 987654321
        }
      ],
      "arguments": [
        {
          "name": "biz",
          "value": "klingai"
        },
        {
          "name": "__initialType",
          "value": "mmu_img2img_aiweb"
        },
        {
          "name": "__initialPrompt",
          "value": "Portrait of a woman with blue eyes"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "mmu_image_upscale_aiweb",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Task 123456789 is not completed"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/images/upscale" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "task_id": "123456789",
     "workId": "987654321"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/upscale"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    task_id: "123456789",
    workId: "987654321"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/upscale"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "task_id": "123456789",
    "workId": "987654321"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-images-virtual-try-on ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-virtual-try-on
## Virtual Try-On
<small>April 18, 2025 (October 1, 2025)</small>

---

This endpoint allows you to create virtual try-on images with Kling AI by providing a human image and clothing items.
> **https://api.useapi.net/v1/kling/images/virtual-try-on**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "humanImage": "https://example.com/person.jpg",
  "dressInput": "https://example.com/dress.jpg",
  "imageCount": 2,
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `humanImage` is **required**, URL to the image of a person.  
  Must be a valid http/https URL. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.

- `dressInput` URL to a full-dress image to try on.  
  Incompatible with upperInput and lowerInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets).

- `upperInput` URL to an upper garment image.  
  Incompatible with dressInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets).
   
- `lowerInput` URL to a lower garment image.  
  Incompatible with dressInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets).

- `imageCount` is optional, range from `1` to `4`.  
  Default is `1`.

- `maxJobs` is optional, range from `1` to `50`.  
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.
  
- `replyRef` is optional, a reference identifier for the callback.

**Note:** You must provide at least one of: `dressInput`, `upperInput`, or `lowerInput`.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "mmu_img2img_aitryon",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "mmu_img2img_aitryon",
      "inputs": [
        {
          "name": "humanImage",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/person.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "dressInput",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/dress.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "personType",
          "value": "Female"
        },
        {
          "name": "imageCount",
          "value": "2"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "mmu_img2img_aitryon",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "At least one of dressInput, upperInput or lowerInput must be provided"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/images/virtual-try-on" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "humanImage": "https://example.com/person.jpg",
     "dressInput": "https://example.com/dress.jpg",
     "imageCount": 2
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/virtual-try-on"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    humanImage: "https://example.com/person.jpg",
    dressInput: "https://example.com/dress.jpg",
    imageCount: 2
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/virtual-try-on"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "humanImage": "https://example.com/person.jpg",
    "dressInput": "https://example.com/dress.jpg",
    "imageCount": 2
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-tts-create ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-tts-create
## Generate speech from text
<small>April 18, 2025 (December 15, 2025)</small>

---

This endpoint generates speech up to **5 minutes** long from text using Kling's text-to-speech technology.

You can execute an unlimited number of TTS generations for **free**. This feature is available for all Kling subscription plans, including the free one.
> **https://api.useapi.net/v1/kling/tts/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "speakerId": "speakerId",
  "text": "Text to be converted to speech",
  "speed": 1.0,
  "emotion": "happy"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `speakerId` is **required**, a valid speakerId from [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices).  
  
- `text` is **required**, the text to be converted to speech.  
  
- `speed` is optional, range from `0.8` to `2.0`.   
  Default is `1.0`.

- `emotion` is optional, must be one of the supported emotion keys for the selected voice.  

##### Responses 

**200**
**200 OK**
```json
{
  "resource": "https://s21-kling.klingai.com/....mp3",
  "status": 99,
  "duration": 195621,
  "status_name": "succeed",
  "status_final": true
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

Field `resource` will contain URL with generated mp3 audio file.

##### Model
```typescript
{ // TypeScript, all fields are optional
  resource: string        // URL to the generated MP3 audio file
  status: number          // Status code, e.g., 99 for succeed
  duration: number        // Duration, seconds
  status_name: 'submitted' | 'failed' | 'processing' | 'succeed'  // Status name
  status_final: boolean   // Whether this is the final status
  message: string
  error: string
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/tts/create" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{"email":"user@example.com","speakerId":"speakerId","text":"Hello, world!"}'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/tts/create"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    speakerId: "speakerId",
    text: "Hello, world!"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/tts/create"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "speakerId": "speakerId",
    "text": "Hello, world!"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-add-sound ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-add-sound
## Add sound to Kling video
<small>August 8, 2025 (October 1, 2025)</small>

---

This endpoint generates sound for an existing video using Kling's AI audio generation capabilities. 

Video can't be shorter than 3 seconds or longer than 20 seconds.
> **https://api.useapi.net/v1/kling/videos/add-sound**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body

``` json
{
  "video": "https://s21-kling.klingai.com/....mp4",
  "replyUrl": "https://my.domain.com/webhook-endpoint-kling",
  "replyRef": "my-id-1234"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `video` is **required**, the URL of the video to add sound to.   
  Video can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here.   
  Video can't be shorter than 3 seconds or longer than 20 seconds.  

- `cropVideoOriginalSound` is optional, whether to preserve the original video's sound.  
  Default `false` (original sound will be replaced).

- `maxJobs` is optional, the maximum number of concurrent Kling jobs.  

- `replyUrl` is optional, a URL to receive webhooks when the video is completed.
  Callback body has the same JSON shape as [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) response.

- `replyRef` is optional, include a custom reference to identify the job.  
  Passed as-is to the `replyUrl` webhook.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 1234567890,
    "userId": 12345,
    "type": "kwave_video2audio",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "taskInfo": {
      "type": "kwave_video2audio",
      "inputs": [
        {
          "name": "video",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://v15-kling.klingai.com/…",
          "cover": null,
          "fromWorkId": null,
          "fromUploadId": null
        }
      ],
      "arguments": [
        {
          "name": "biz",
          "value": "klingai"
        },
        {
          "name": "imageCount",
          "value": "1"
        },
        {
          "name": "duration",
          "value": "20"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [
        {
          "name": "video2audio_payloads",
          "resources": [
            {
              "name": "originalVideoUrl",
              "type": "VIDEO",
              "url": "https://v15-kling.klingai.com/…"
            }
          ],
          "arguments": [
            {
              "name": "cropVideoOriginalSound",
              "value": "false"
            }
          ]
        }
      ],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1754630611379,
    "updateTime": 1754630611379,
    "viewTime": 0,
    "status_name": "submitted",
    "status_final": false
  },
  "works": [],
  "status": 5,
  "message": "",
  "limitation": null,
  "userPoints": {
    "points": [
      {
        "orderId": "1234567890",
        "type": "reward",
        "amount": 26600,
        "balance": 3150,
        "startTime": 1754406534079,
        "endTime": 1757084934079
      }
    ],
    "total": 113390
  },
  "userTickets": {
    "ticket": [
      {
        "orderId": "1234456789",
        "type": "priority",
        "packageType": "reward",
        "amount": 1,
        "balance": 1,
        "startTime": 1754406534079,
        "endTime": 1757084934079
      }
    ]
  },
  "editProject": null,
  "status_name": "submitted",
  "status_final": false
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Invalid video URL format"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number              // Unique task identifier
        userId: number          // User ID
        type: string            // Task type: "kwave_video2audio"
        scene: string           // Scene type: "NORMAL_CREATION"
        status: number          // Task status 
        taskInfo: {
            type: string        // Task type
            inputs: {
                name: string    // Input name: "video"
                inputType: string // Input type: "URL"
                token: string | null
                blobStorage: string | null
                url: string     // Video URL
                cover: string | null
                fromWorkId: number | null
                fromUploadId: number | null
            }[]
            arguments: {
                name: string    // Argument name
                value: string   // Argument value
            }[]
            extraArgs: Record<string, any>
            callbackPayloads: {
                name: string    // "video2audio_payloads"
                resources: {
                    name: string    // "originalVideoUrl"
                    type: string    // "VIDEO"
                    url: string     // Original video URL
                    marginTop?: number
                    countInRow?: number
                    mode?: string
                }[]
                arguments: {
                    name: string    // Parameter name
                    value: string   // Parameter value
                }[]
            }[]
            scene: string       // Scene type
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number      // Creation timestamp
        updateTime: number      // Update timestamp
        viewTime: number        // View timestamp
        status_name: string     // Status name: "submitted"
        status_final: boolean   // Whether status is final
    }
    works: any[]                // Work items (empty initially)
    status: number              // Overall status
    message: string             // Status message
    error: string
    limitation: any | null      // Rate limiting info
    userPoints: {
        points: {
            orderId: string     // Order ID
            type: string        // Point type
            amount: number      // Point amount
            balance: number     // Remaining balance
            startTime: number   // Start timestamp
            endTime: number     // End timestamp
        }[]
        total: number           // Total points
    }
    userTickets: {
        ticket: {
            orderId: string     // Order ID
            type: string        // Ticket type
            packageType: string // Package type
            amount: number      // Ticket amount
            balance: number     // Remaining balance
            startTime: number   // Start timestamp
            endTime: number     // End timestamp
        }[]
    }
    editProject: any | null     // Edit project info
    status_name: string         // Status name
    status_final: boolean       // Whether status is final
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/kling/videos/add-sound" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer …" \
  -d '{
    "email": "user@domain.com",
    "video": "https://s21-kling.klingai.com/....mp4",
    "replyUrl": "https://my.domain.com/webhook-endpoint-kling"
  }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const requestData = {
  email,
  video: "https://s21-kling.klingai.com/....mp4",
  replyUrl: "https://my.domain.com/webhook-endpoint-kling"
};
const response = await fetch("https://api.useapi.net/v1/kling/videos/add-sound", {
  method: "POST",
  headers: {
    "Content-Type": "application/json", 
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify(requestData)
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
request_data = {
    "email": email,
    "video": "https://s21-kling.klingai.com/....mp4",
    "replyUrl": "https://my.domain.com/webhook-endpoint-kling"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
response = requests.post("https://api.useapi.net/v1/kling/videos/add-sound", 
                        headers=headers, 
                        json=request_data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-extend ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-extend
## Extend an Existing Video
<small>April 18, 2025 (October 1, 2025)</small>

---

This endpoint extends a previously generated video, continuing the animation from where it left off.
> **https://api.useapi.net/v1/kling/videos/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "task_id": "12345678",
  "prompt": "Continue with the mountain landscape, now showing a sunset",
  "negative_prompt": "people, low quality, distorted",
  "cfg_scale": 0.5,
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `task_id` is **required**, the ID of a completed video generation task to extend.   
  You can get a list of your tasks from [GET /tasks](/docs/api-kling-v1/get-kling-tasks).
  
- `prompt` is optional, text description to guide the extended video generation.   
  Maximum length: 2500 characters.
  
- `negative_prompt` is optional, what not to include in the generated video.   
  Maximum length: 2500 characters.
  
- `cfg_scale` is optional, guidance scale for video extension.   
  Range: `0` to `1`. Default: `0.5`.

- `enable_audio` is optional, add sound effects.      
  Supported values: `false` (default) or `true`.  
  
- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Note:** The task specified by `task_id` must be in the `succeed` status for the extension to work.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_extend_video",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_extend_video",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/video12345.mp4",
          "cover": null,
          "fromWorkId": 12345678
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "Continue with the mountain landscape, now showing a sunset"
        },
        {
          "name": "negative_prompt",
          "value": "people, low quality, distorted"
        },
        {
          "name": "cfg",
          "value": "0.5"
        },
        {
          "name": "__initialType",
          "value": "m2v_txt2video_hq"
        },
        {
          "name": "__initialPrompt",
          "value": "A majestic mountain landscape with snow-capped peaks and flowing rivers"
        },
        {
          "name": "kling_version",
          "value": "1.6"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_extend_video",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Task is not completed"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/extend" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "task_id": "12345678",
     "prompt": "Continue with the mountain landscape, now showing a sunset",
     "negative_prompt": "people, low quality, distorted"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/extend"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    task_id: "12345678",
    prompt: "Continue with the mountain landscape, now showing a sunset",
    negative_prompt: "people, low quality, distorted"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/extend"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "task_id": "12345678",
    "prompt": "Continue with the mountain landscape, now showing a sunset",
    "negative_prompt": "people, low quality, distorted"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects
## Create Video From Image with Effects
<small>April 18, 2025 (October 1, 2025)</small>

---

This endpoint generates a video from an image using special effects.
> **https://api.useapi.net/v1/kling/videos/image2video-effects**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "effect": "rocket",
  "image": "https://example.com/image.jpg",
  "prompt": "A detailed description for the effect",
  "mode": "std",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `effect` is **required**, the name of the effect to apply.   
  Get available effects from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects).
  
- `image` is **required**, URL to the image to animate.   
  Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `prompt` is optional, text description to guide the effect.   
  Some effects support custom prompts while others use default prompts. Maximum length: 2500 characters.
  
- `mode` is optional, generation quality mode. Accepted values: `std` (standard), `pro` (professional).   
  Defaults to `std`. Not all effects support all modes - check the effect details from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects).
  
- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Notes:**
- Different effects have different capabilities. Check the response from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects) to see if an effect supports custom prompts and which modes are available.
- Effects marked as `effectSupported: false` require image preprocessing and are not yet supported.
- Effects with `promptSupported: true` accept custom prompts, while others use built-in default prompts.
- The `mode` parameter allows selection between standard and professional quality where supported.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2video_se_hq",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_img2video_se_hq",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/image.jpg",
          "cover": null,
          "fromWorkId": null,
          "fromUploadId": null
        }
      ],
      "arguments": [
        {
          "name": "special_effect",
          "value": "expansion"
        },
        {
          "name": "prompt",
          "value": "A detailed description for the effect"
        },
        {
          "name": "kling_version",
          "value": "1.6"
        },
        {
          "name": "model_mode",
          "value": "std"
        },
        {
          "name": "seStepName",
          "value": "seSubmit"
        },
        {
          "name": "biz",
          "value": "klingai"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1753424884354,
    "updateTime": 1753424884354,
    "viewTime": 0
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": null,
  "userPoints": {
    "points": [
      {
        "orderId": "…",
        "type": "recharge",
        "amount": 66000,
        "balance": 25540,
        "startTime": 1752894669788,
        "endTime": 1815966669788
      }
    ],
    "total": 25540
  },
  "userTickets": {
    "ticket": [
      {
        "orderId": "…",
        "type": "priority",
        "packageType": "reward",
        "amount": 1,
        "balance": 1,
        "startTime": 1751329144926,
        "endTime": 1754007544926
      }
    ]
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Effect rocket not found. Supported effects: cartoon,cyberpunk,spinoff"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-effects" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "effect": "rocket",
     "image": "https://example.com/image.jpg"
  }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-effects"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    effect: "rocket",
    image: "https://example.com/image.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-effects"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "effect": "rocket",
    "image": "https://example.com/image.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-elements
## Create Video From Multiple Images
<small>April 18, 2025 (April 24, 2026)</small>

---

This endpoint generates a video from multiple images (up to 4) that will appear as elements in the video.

Model `3.0` additionally supports saved [elements](/docs/api-kling-v1/get-kling-elements) via `element_1`-`element_3` parameters, with a combined maximum of 3 images/elements.

##### Model Support Matrix

| Feature | v3.0 | v1.6 |
|---------|:----:|:----:|
| Image inputs (`image_0`-`image_3`) | ✅ | ✅ |
| Element inputs (`element_1`-`element_3`) | ✅ | ❌ |
| Max combined inputs | 3 | 4 |
| Duration | 3-15s | 5/10s |
| Audio | Always on | Optional |
| aspect_ratio | ❌ (from image) | ✅ |
> **https://api.useapi.net/v1/kling/videos/image2video-elements**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A museum gallery with artwork on display",
  "image_0": "https://example.com/image1.jpg",
  "image_1": "https://example.com/image2.jpg",
  "image_2": "https://example.com/image3.jpg",
  "image_3": "https://example.com/image4.jpg",
  "negative_prompt": "low quality, blurry, distorted",
  "duration": "5",
  "aspect_ratio": "16:9",
  "model_name": "kling-v1-6",
  "mode": "std",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `prompt` is **required**, text description of the video to generate.   
  Maximum length: 2500 characters.
  
- `image_0` to `image_3` are URLs to images that will appear in the video. At least one image or element must be provided.
  Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.

- `element_1` to `element_3` are optional, IDs of saved [elements](/docs/api-kling-v1/get-kling-elements). Model `3.0` only.
  Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements).
  Combined total of images + elements cannot exceed 3 for model `3.0`.

- `negative_prompt` is optional, what not to include in the generated video.
  Maximum length: 2500 characters.

- `duration` is optional, length of the video in seconds.
  Model `3.0`: `3` to `15` seconds (default `5`).
  Model `1.6`: `5` (default) or `10`.

- `aspect_ratio` is optional, the video aspect ratio.
  Supported values: `16:9` (default), `9:16`, `1:1`.
  Model `3.0` does not support this parameter (aspect ratio is derived from input image).

- `model_name` is optional, the AI model version to use.
  Supported values: `kling-v3-0`, `kling-v1-6` (default).

- `mode` is optional, quality level.
  Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, model `3.0` only).

- `enable_audio` is optional, add sound effects.
  Supported values: `false` (default) or `true`.
  Model `3.0` defaults to audio enabled; set `enable_audio: false` to disable.
  
- `maxJobs` is optional, range from `1` to `50`.    
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.  

**Note:** At least one image or element must be provided. For model `1.6`, at least one of `image_0`-`image_3` is required. For model `3.0`, elements (`element_1`-`element_3`) alone are also sufficient.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2video_hq",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_img2video_hq",
      "inputs": [
        {
          "name": "ref_img_0",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/image1.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "raw_ref_img_0",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/image1.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "ref_img_1",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/image2.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "raw_ref_img_1",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/image2.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A museum gallery with artwork on display"
        },
        {
          "name": "negative_prompt",
          "value": "low quality, blurry, distorted"
        },
        {
          "name": "duration",
          "value": "5"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        },
        {
          "name": "kling_version",
          "value": "1.6"
        },
        {
          "name": "imageList",
          "value": "[{\"top\":0,\"left\":0,\"width\":1,\"height\":1},{\"top\":0,\"left\":0,\"width\":1,\"height\":1}]"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_img2video_hq",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "At least one image (image_0, image_1, image_2 or image_3) is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-elements" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "prompt": "A museum gallery with artwork on display",
     "image_0": "https://example.com/image1.jpg",
     "image_1": "https://example.com/image2.jpg",
     "negative_prompt": "low quality, blurry, distorted"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-elements"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "A museum gallery with artwork on display",
    image_0: "https://example.com/image1.jpg",
    image_1: "https://example.com/image2.jpg",
    negative_prompt: "low quality, blurry, distorted"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-elements"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "A museum gallery with artwork on display",
    "image_0": "https://example.com/image1.jpg",
    "image_1": "https://example.com/image2.jpg",
    "negative_prompt": "low quality, blurry, distorted"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-frames ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-frames
## Create Video From Image Frames
<small>April 18, 2025 (April 24, 2026)</small>

---

This endpoint generates a video from one or two images (start and end frames).

| Model | Start Frame<br>`image` | End Frame<br>`image_tail` | Audio<br>`enable_audio` | Multi-shot | Duration |
|-------|:-----------:|:---------:|:------------:|:----------:|:--------:|
| kling-v3-0 | ✅<br>Required | ✅ | ✅<br>Default on | ✅ | 3-15s |
| kling-v2-6 | ✅<br>Required | ✅<br>Pro only | ✅<br>Native Audio<br>Pro, Start Frame only | ❌ | 5/10s |
| kling-v2-5 | ✅<br>Required | ✅<br>Pro only | ✅<br>Sound Effects | ❌ | 5/10s |
| kling-v2-1 | ✅<br>Required | ✅ | ✅<br>Sound Effects | ❌ | 5/10s |
| kling-v2-1-master<br>(pro only) | ✅<br>Required | ❌ | ✅<br>Sound Effects | ❌ | 5/10s |
| kling-v1-6 | ✅ | ✅ | ✅<br>Sound Effects | ❌ | 5/10s |
| kling-v1-5 | ✅ | ✅ | ✅<br>Sound Effects | ❌ | 5/10s |
> **https://api.useapi.net/v1/kling/videos/image2video-frames**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "image": "https://example.com/start-image.jpg",
  "prompt": "A futuristic city with flying cars and tall buildings",
  "negative_prompt": "people, low quality, distorted",
  "duration": "10",
  "model_name": "kling-v2-5",
  "mode": "pro",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `image` is required if `image_tail` is not provided. URL to the start frame image. Required for models `2.x`.   
  Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `image_tail` is required if `image` is not provided. URL to the end frame image. Model `2.1 Master` does not support this parameter.
  Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here.
  
- `prompt` is optional, text description to guide the video generation.
  Maximum length: 2500 characters.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  
- `negative_prompt` is optional, what not to include in the generated video. Models `2.5`, `2.6`, and `3.0` do not support this parameter.    
  Maximum length: 2500 characters.
  
- `cfg_scale` is optional, guidance scale for image-to-video generation. Models `2.x` do not support this parameter.      
  Range: `0` to `1`. Default: `0.5`.
  
- `duration` is optional, length of the video in seconds.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  Model `3.0`: `3` to `15` seconds (default `5`).
  Other models: `5` (default) or `10`.

- `model_name` is optional, the AI model version to use.
  Supported values: `kling-v3-0`, `kling-v2-6`, `kling-v2-5`, `kling-v2-1` (default), `kling-v2-1-master`, `kling-v1-6`, `kling-v1-5`.
  Model `3.0` does not support `aspect_ratio` (derived from input image). Audio is enabled by default; set `enable_audio: false` to disable.
  
- `mode` is optional, quality level. Model `2.1 Master` only supports `pro` mode.
  Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, model `3.0` only).
  Model `2.6` supports `std` and `pro`, but `pro` is required when `enable_audio` is `true`.
  Model `3.0` adds support for `4k`.

- `enable_audio` is optional, add audio to the generated video.
  Supported values: `false` (default) or `true`.
  Model `3.0` defaults to audio enabled; set `enable_audio: false` to disable.
  Model `2.6`: Native Audio (AI-generated audio synced with video), requires `mode: pro`, not available with End Frame.
  Other models: Sound Effects (basic audio generation).

- `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts for multi-shot storytelling (v3 only).
  Maximum length: 2500 characters per shot.
  Minimum 2 shots required. Cannot be used together with `prompt` or `duration`.

- `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds.
  Each shot must have both prompt and duration. Total duration must be 3-15 seconds.
  Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`).

- `maxJobs` is optional, range from `1` to `50`.    
  Specifies the maximum number of concurrent jobs.
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Notes:**
- At least one of `image` or `image_tail` must be provided.
- If `image_tail` provided, the mode is automatically set to `pro`.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2video_hq",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_img2video_hq",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/start-image.jpg",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "tail_image",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/end-image.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A futuristic city with flying cars and tall buildings"
        },
        {
          "name": "negative_prompt",
          "value": "people, low quality, distorted"
        },
        {
          "name": "duration",
          "value": "5"
        },
        {
          "name": "kling_version",
          "value": "2.1"
        },
        {
          "name": "tail_image_enabled",
          "value": "true"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_img2video_hq",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "image or image_tail is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-frames" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "image": "https://example.com/start-image.jpg",
     "image_tail": "https://example.com/end-image.jpg",
     "prompt": "A futuristic city with flying cars and tall buildings",
     "negative_prompt": "people, low quality, distorted"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-frames"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    image: "https://example.com/start-image.jpg",
    image_tail: "https://example.com/end-image.jpg",
    prompt: "A futuristic city with flying cars and tall buildings",
    negative_prompt: "people, low quality, distorted"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-frames"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "image": "https://example.com/start-image.jpg",
    "image_tail": "https://example.com/end-image.jpg",
    "prompt": "A futuristic city with flying cars and tall buildings",
    "negative_prompt": "people, low quality, distorted"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-lipsync ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-lipsync
## Apply Lip Sync to Video
<small>April 18, 2025 (October 1, 2025)</small>

---

This endpoint applies lip sync to a video using an audio file, making the character in the video appear to speak the audio.

Video cannot be longer than 60 seconds. 

We suggest using PixVerse Lip Sync [POST pixverse/videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) for longer videos. PixVerse can lip sync videos over 60 seconds long and has much more relaxed requirements for character face visibility.
> **https://api.useapi.net/v1/kling/videos/lipsync**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "video": "https://example.com/video.mp4",
  "audio": "https://example.com/audio.mp3",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `video` is **required**, URL to the video that contains a face to sync with.  
  Video cannot be longer than 60 seconds.    
  Video can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here.

- `audio` is **required**, URL to the audio file containing speech.   
  Audio can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here.

- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Notes:**
- The video should contain a clear frontal view of a face with lip movements.
- Supported audio formats include MP3, WAV, and other common audio formats.
- If the audio is shorter than the video, the excess video will be muted. 
  If it's longer, the excess audio will be discarded.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_video_lip_sync",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_video_lip_sync",
      "inputs": [
        {
          "name": "video",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/video.mp4",
          "cover": null,
          "fromWorkId": null
        },
        {
          "name": "audio",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://example.com/audio.mp3",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "__filename",
          "value": "audio.mp3"
        },
        {
          "name": "__isLocalAudio",
          "value": "true"
        },
        {
          "name": "biz",
          "value": "klingai"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_video_lip_sync",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter video is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/lipsync" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "video": "https://example.com/video.mp4",
     "audio": "https://example.com/audio.mp3"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/lipsync"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    video: "https://example.com/video.mp4",
    audio: "https://example.com/audio.mp3"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/lipsync"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "video": "https://example.com/video.mp4",
    "audio": "https://example.com/audio.mp3"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create
## Create Video from Motion and Image
<small>October 7, 2025 (March 6, 2026)</small>

---

This endpoint applies motion from a reference video to a static image, creating an animated video where the character in the image performs the motion. Supports Kling v3.0 (default) and v2.6 motion control models. Optionally attach an element for improved character consistency.
> **https://api.useapi.net/v1/kling/videos/motion-create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "model_name": "kling-v3-0",
  "imageUrl": "https://example.com/person.jpg",
  "motionUrl": "https://example.com/dance-video.mp4",
  "prompt": "Person dancing energetically",
  "keepAudio": true,
  "motionDirection": "motion_direction",
  "mode": "std",
  "element_1": "u_123456789012345",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `model_name` is optional, must be `kling-v3-0` or `kling-v2-6`.
  Selects the motion control model version. v3.0 provides upgraded motion capture with high facial consistency.
  Default: `kling-v3-0`

- `imageUrl` is **required**, URL to the image containing the person.
  The person's body and pose should be clearly visible.
  Must be uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) first - use the `url` field from the response.

- `motionUrl` is **required**, URL to the motion reference video (3-30 seconds).
  The video provides the motion that will be applied to the person in the image.
  Use [GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions) to retrieve official Kling motions or your previously uploaded motions.
  To upload a new motion video, use [POST /assets](/docs/api-kling-v1/post-kling-assets) - use the `resourceUrl` field from the response.

- `prompt` is optional, string up to 2500 characters.
  Text description to guide the video generation.

- `keepAudio` is optional, boolean.
  When `true`, preserves the original audio from the motion video.
  Default: `false`

- `motionDirection` is optional, must be `motion_direction` or `image_direction`.
  - `motion_direction` (default): The generated video follows the motion from the reference video
  - `image_direction`: The generated video follows the pose/direction from the source image

- `mode` is optional, must be `std` or `pro`.
  Generation quality mode. Pro mode provides higher quality but costs more.
  Default: `std`

- `element_1` is optional, a saved element ID (e.g., `u_123456789012345`) for improved character consistency. Only supported with `kling-v3-0`.
  Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements). The element's cover image is included in the generation inputs.

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Notes:**
- The image must contain at least one clearly visible person with detectable pose
- The endpoint validates the image before processing - returns error if no character detected
- Video duration is automatically detected from the motion video

##### Responses

**200**
**200 OK**
```json
{
  "task": {
    "id": 299640525521807,
    "userId": 23555898,
    "type": "m2v_motion_control",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_motion_control",
      "inputs": [
        {
          "name": "video",
          "inputType": "URL",
          "url": "https://example.com/dance-video.mp4",
          "cover": ""
        },
        {
          "name": "image",
          "inputType": "URL",
          "url": "https://example.com/person.jpg"
        }
      ],
      "arguments": [
        { "name": "biz", "value": "klingai" },
        { "name": "prompt", "value": "Person dancing energetically" },
        { "name": "duration", "value": 5.76 },
        { "name": "imageCount", "value": 1 },
        { "name": "kling_version", "value": "3.0" },
        { "name": "keep_original_sound", "value": false },
        { "name": "motion_direction", "value": "motion_direction" },
        { "name": "model_mode", "value": "std" }
      ],
      "callbackPayloads": [
        { "name": "motionFrom", "value": "LOCAL" }
      ]
    },
    "createTime": 1767669665000,
    "updateTime": 1767669665000
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": ""
}
```

**400**
**400 Bad Request**

Image validation failed - no detectable character in image:
```json
{
  "status": 1,
  "message": "MOTION.PIC_NOT_MATCHED"
}
```

Missing required parameter:
```json
{
  "error": "Parameter imageUrl is required"
}
```

Insufficient credits:
```json
{
  "error": {
    "type": "TASK.PointNotEnough",
    "detail": "Credit are insufficient, please top up and try again."
  }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string // "m2v_motion_control"
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                url: string
                cover?: string
            }>
            arguments: Array<{
                name: string
                value: string | number | boolean
            }>
            callbackPayloads: Array<{
                name: string
                value: string
            }>
        }
        createTime: number
        updateTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error?: {
        type: string
        detail: string
    }
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/motion-create" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "model_name": "kling-v3-0",
     "imageUrl": "https://s15-kling.klingai.com/.../person.jpg",
     "motionUrl": "https://v15-kling.klingai.com/.../dance.mp4",
     "prompt": "Person dancing energetically",
     "keepAudio": true,
     "mode": "std",
     "element_1": "u_123456789012345"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/motion-create";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    model_name: "kling-v3-0",
    imageUrl: "https://s15-kling.klingai.com/.../person.jpg",
    motionUrl: "https://v15-kling.klingai.com/.../dance.mp4",
    prompt: "Person dancing energetically",
    keepAudio: true,
    mode: "std",
    element_1: "u_123456789012345"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/motion-create"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "model_name": "kling-v3-0",
    "imageUrl": "https://s15-kling.klingai.com/.../person.jpg",
    "motionUrl": "https://v15-kling.klingai.com/.../dance.mp4",
    "prompt": "Person dancing energetically",
    "keepAudio": True,
    "mode": "std",
    "element_1": "u_123456789012345"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-upload ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-upload
## Upload Custom Motion
<small>October 7, 2025 (January 6, 2026)</small>

<span class="required-input-field"><b>This endpoint is no longer used.</b></span>

---

This endpoint allows you to upload a custom video to extract motion data from it. The extracted motion can then be used with the [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) endpoint to apply the motion to different images.
> **https://api.useapi.net/v1/kling/videos/motion-upload**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "resourceUrl": "https://s21-kling.klingai.com/.../video.mp4",
  "coverUrl": "https://s21-kling.klingai.com/.../image.jpg",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `resourceUrl` is **required**, URL to the video containing the motion to extract.
  Video should show a person performing the motion you want to capture.  
  Must be uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) first - use the `resourceUrl` field from the response.

- `coverUrl` is **required**, URL to a cover image for the motion.
  Must be uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) first - use the `coverUrl` field from the response.

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.  

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

**Notes:**
- The video **must be between 2 and 10 seconds long**, otherwise it will be rejected
- The video should contain a clear view of a person performing the desired motion
- The system will extract the motion data (BVH and binary formats) from the video
- Once processed, the motion will appear in your user motions list ([GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions) with `mine=true`)
- To delete a user-uploaded motion, use [DELETE /tasks/`task_id`](/docs/api-kling-v1/del-kling-tasks-task_id) with the motion's `taskId` from the motions list

##### Responses

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "motion_control_motion_process",
    "scene": "MOTION_EXTRACTION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "motion_control_motion_process",
      "inputs": [
        {
          "name": "input",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/.../video.mp4",
          "cover": "https://s21-kling.klingai.com/.../image.jpg",
          "fromWorkId": 0,
          "fromUploadId": ""
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": ""
        },
        {
          "name": "motionType",
          "value": "video2motion"
        },
        {
          "name": "biz",
          "value": "klingai"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "MOTION_EXTRACTION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "motion_control_motion_process",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter resourceUrl is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). Once processing completes, the extracted motion will be available in [GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions) with `mine=true`.

##### Model
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number
                fromUploadId: string
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/motion-upload" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "resourceUrl": "https://s21-kling.klingai.com/.../video.mp4",
     "coverUrl": "https://s21-kling.klingai.com/.../image.jpg"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/motion-upload";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    resourceUrl: "https://s21-kling.klingai.com/.../video.mp4",
    coverUrl: "https://s21-kling.klingai.com/.../image.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/motion-upload"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "resourceUrl": "https://s21-kling.klingai.com/.../video.mp4",
    "coverUrl": "https://s21-kling.klingai.com/.../image.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-omni ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-omni
## Generate Videos with Omni
<small>December 11, 2025 (April 24, 2026)</small>

---

This endpoint generates videos using Kling's Omni model (`O1` and `v3`). It supports multiple workflows for different use cases:

- **Default workflow**: Text-to-video with optional image/element references
- **Frames workflow**: Generate video between start and end frame images
- **Video Reference workflow**: Use a reference video to guide generation style
- **Video Transform workflow**: Transform/modify a reference video

##### Version Comparison

| Feature | v3 | O1 |
|---------|:--:|:--:|
| Duration | 3-15s | 3-10s |
| Multi-shot | ✅ | ❌ |
| Aspect Ratio | `16:9` (default), `9:16`, `1:1` | `16:9` (default), `9:16`, `1:1` |
| Aspect Ratio `auto` | Frames workflow only | Frames workflow only |
| VIDEO elements | ✅ | ❌ (IMAGE only) |
> **https://api.useapi.net/v1/kling/videos/omni**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A woman @image_1 dancing elegantly in a ballroom",
  "duration": "5",
  "aspect_ratio": "16:9",
  "count": 1,
  "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required** (unless using multi-shot), the text description of the video to generate.
  Maximum length: 1700 characters.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  Use `@image_1`, `@image_2`, etc. to reference images in your prompt.
  Use `@element_1`, `@element_2`, etc. (or `@object_1`, etc.) to reference saved elements.
  Use `@video_1` to reference a video in your prompt.

- `omni_version` is optional, the Omni model version to use.
  Supported values: `o1`, `v3` (default).

- `mode` is optional, the generation mode.
  Supported values: `std` (default), `pro`, or `4k` (4K resolution, `omni_version: v3` only).

###### Workflow Selection

The workflow is automatically determined based on which inputs you provide:

| Inputs Provided | Workflow |
|-----------------|----------|
| `frame_start` (with optional `frame_end`) | Frames |
| `video_1` with `video_mode=transform` | Video Transform |
| `video_1` with `video_mode=reference` (default) | Video Reference |
| Images/elements only, or text-only | Default |

###### Default Workflow (Images/Elements)

Use images and/or saved elements as references in your prompt.

- `image_1` through `image_7` are optional, URLs of reference images.
  You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets).
  Reference in prompt using `@image_1`, `@image_2`, etc.

- `element_1` through `element_7` are optional, IDs of saved elements.
  Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements).
  Reference in prompt using `@element_1` or `@object_1`, etc.

**Note:** Images and elements share the same pool of 7 slots. Combined total cannot exceed 7.

###### Frames Workflow

Generate video that transitions between a start frame and optional end frame.

- `frame_start` is required for frames workflow, URL of the start frame image.
  Internally mapped to `image_1`.

- `frame_end` is optional, URL of the end frame image.
  Internally mapped to `image_2`.
  Cannot be used without `frame_start`.

**Restrictions:** When using frames workflow, `image_N`, `element_N`, and `video_1` are not allowed.

###### Video Reference/Transform Workflow

Use a reference video to guide generation or transform it directly.

- `video_1` is optional, URL of a reference video.
  You can upload videos using [POST /assets](/docs/api-kling-v1/post-kling-assets).
  Reference in prompt using `@video_1`.
  Video must be 3-10 seconds long (O1) or 3-15 seconds (v3).

- `video_mode` is optional, how to use the video reference.
  Supported values: `reference` (default), `transform`.
  - `reference`: Video guides the style/motion of generated content
  - `transform`: Video is directly transformed/modified

- `keep_audio` is optional, whether to keep audio from the reference video.
  Default: `false`.
  Only applies when `video_1` is provided.

**Note:** When using `video_1`, you can still include up to 4 images/elements (combined).

###### Duration Support Matrix

Duration availability depends on the workflow, inputs, and version:

| Scenario | O1 Durations | v3 Durations | Notes |
|----------|-------------|--------------|-------|
| Text-only (no inputs) | `5`, `10` | `3`-`15` | O1 restricted |
| Single start frame only | `5`, `10` | `3`-`15` | O1 restricted |
| Images/elements provided | `3`-`10` | `3`-`15` | Full range |
| Both frames (start + end) | `3`-`10` | `3`-`15` | Full range |
| With `video_1` | **Locked** to video length | **Locked** to video length | Cannot be changed |

- `duration` is optional, the duration in seconds.
  Default: `5`.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  **VIP required** for durations `7`-`10` (O1) or `7`-`15` (v3).
  When `video_1` is provided, duration is auto-detected and cannot be overridden.

###### Aspect Ratio Support Matrix

| Workflow | Allowed Values | Default |
|----------|---------------|---------|
| Default (text/images/elements) | `16:9`, `9:16`, `1:1` | `16:9` |
| Frames workflow | `auto` only | `auto` |
| Video Reference/Transform | `16:9`, `9:16`, `1:1` | `16:9` |

- `aspect_ratio` is optional.
  When using `frame_start`, aspect ratio is always `auto` (derived from input).
  `auto` is NOT allowed for other workflows.

###### Input Limits Matrix

| Workflow | Max Images | Max Elements | Max Combined | Max Video |
|----------|------------|--------------|--------------|-----------|
| Default | 7 | 7 | 7 | 0 |
| Frames | 0 | 0 | 0 | 0 |
| Video Reference | 4 | 4 | 4 | 1 |
| Video Transform | 4 | 4 | 4 | 1 |

###### Multi-shot (v3 only)

Split a video into multiple shots, each with its own prompt and duration. Useful for storytelling with scene transitions.

- `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts.
  Maximum length: 2500 characters per shot.
  Minimum 2 shots required. Cannot be used together with `prompt` or `duration`.
  Use `@image_1`, `@element_1`, etc. references within shot prompts.

- `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds.
  Each shot must have both prompt and duration. Total duration must be 3-15 seconds.
  Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`).

###### Other Parameters

- `count` is optional, the number of videos to generate.
  Range: `1` to `4`. Default: `1`.
  **VIP required** for counts `2`-`4`.

- `maxJobs` is optional, range from `1` to `50`.
  Specifies the maximum number of concurrent jobs.

- `replyUrl` is optional, a callback URL to receive generation progress and result.
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Prompt Reference Syntax

Reference your inputs in the prompt using these patterns:

| Input Type | Prompt Syntax | Example |
|------------|---------------|---------|
| Images | `@image_1`, `@image_2`, ... | `"A woman @image_1 dancing..."` |
| Elements | `@element_1` or `@object_1`, ... | `"Character @element_1 walks..."` |
| Frames | `@image_1`, `@image_2` | `"Scene transitions from @image_1 to @image_2"` |
| Video | `@video_1` | `"Scene like @video_1 but in winter"` |

##### Responses

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_omni_video",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_omni_video",
      "inputs": [
        {
          "name": "image_1",
          "inputType": "URL",
          "token": null,
          "blobStorage": null,
          "url": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
          "cover": null,
          "fromWorkId": null
        }
      ],
      "arguments": [
        {
          "name": "prompt",
          "value": "A woman Image1 dancing elegantly in a ballroom"
        },
        {
          "name": "rich_prompt",
          "value": "A woman <<<image_1>>> dancing elegantly in a ballroom"
        },
        {
          "name": "kling_version",
          "value": "o1"
        },
        {
          "name": "model_mode",
          "value": "pro"
        },
        {
          "name": "duration",
          "value": "5"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        },
        {
          "name": "imageCount",
          "value": "1"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1733836800000,
    "updateTime": 1733836800000
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_omni_video",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "<error message>"
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
# Default workflow with image
curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "A woman @image_1 dancing elegantly in a ballroom",
     "duration": "5",
     "aspect_ratio": "16:9",
     "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg"
   }'

# Using saved element
curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "Character @element_1 walking through a garden",
     "duration": "5",
     "element_1": "u_123456789012345"
   }'

# Frames workflow
curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "Smooth transition from @image_1 to @image_2",
     "duration": "5",
     "frame_start": "https://s21-kling.klingai.com/ai-platform/xxx/start.jpg",
     "frame_end": "https://s21-kling.klingai.com/ai-platform/xxx/end.jpg"
   }'

# Video reference workflow
curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "user@example.com",
     "prompt": "Scene like @video_1 but in a winter setting",
     "video_1": "https://s21-kling.klingai.com/ai-platform/xxx/reference.mp4",
     "video_mode": "reference"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/omni";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "Character @element_1 dancing elegantly",
    duration: "5",
    aspect_ratio: "16:9",
    element_1: "u_123456789012345"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/omni"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "Character @element_1 walking through garden",
    "duration": "5",
    "aspect_ratio": "16:9",
    "element_1": "u_123456789012345"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video
## Create Video From Text
<small>April 18, 2025 (April 24, 2026)</small>

---

This endpoint generates a video based on a text prompt.

##### Model Support Matrix

| Feature | v3.0 | v2.6 | v2.5 | v2.1 Master | v1.5/v1.6 |
|---------|:----:|:----:|:----:|:-----------:|:----:|
| Duration | 3-15s | 5/10s | 5/10s | 5/10s | 5/10s |
| Mode std | ✅ | ✅ | ❌ | ❌ | ✅ |
| Mode pro | ✅ | ✅ | ✅ | ✅ | ✅ |
| Audio | ✅<br>Default on | ✅<br>Native Audio<br>(Pro) | ✅<br>Sound Effects | ✅<br>Sound Effects | ✅<br>Sound Effects |
| Multi-shot | ✅ | ❌ | ❌ | ❌ | ❌ |
| cfg_scale | ❌ | ❌ | ❌ | ❌ | ✅ |
> **https://api.useapi.net/v1/kling/videos/text2video**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "email": "user@example.com",
  "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers",
  "negative_prompt": "people, buildings, text, low quality",
  "duration": "10",
  "model_name": "kling-v2-1-master",
  "aspect_ratio": "16:9",
  "replyUrl": "https://your-callback-url.com/webhook",
  "replyRef": "your-reference-id"
}
```

- `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured.   
  However, if you have multiple accounts configured, this parameter becomes **required**.
  
- `prompt` is **required** (unless using multi-shot), the text description of the video to generate.
  Maximum length: 2500 characters.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  
- `negative_prompt` is optional, what not to include in the generated video. Models `2.5`, `2.6`, and `3.0` do not support this parameter.   
  Maximum length: 2500 characters.
  
- `cfg_scale` is optional, guidance scale for text-to-video generation. Models `2.x` do not support this parameter.    
  Range: `0` to `1`. Default: `0.5`.
  
- `duration` is optional, length of the video in seconds.
  Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`).
  Supported values depend on `model_name`:

  | Model | Supported Durations |
  |-------|-------------------|
  | kling-v3-0 | `3`, `4`, `5` (default), `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` |
  | kling-v2-6, v2-5, v2-1-master, v1-6, v1-5 | `5` (default), `10` |

- `model_name` is optional, the AI model version to use.
  Supported values: `kling-v3-0`, `kling-v2-6`, `kling-v2-5`, `kling-v2-1-master`, `kling-v1-6` (default), `kling-v1-5`.

- `aspect_ratio` is optional, the video aspect ratio.
  Supported values: `16:9` (default), `9:16`, `1:1`.

- `mode` is optional, quality level. Models `2.1 Master` and `2.5` only support `pro` mode.
  Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, model `3.0` only).
  Model `2.6` supports `std` and `pro`, but `pro` is required when `enable_audio` is `true`.
  Model `3.0` adds support for `4k`.

- `enable_audio` is optional, add sound effects (Native Audio for models `2.6` and `3.0`).
  Supported values: `false` (default) or `true`.
  Model `2.6` with `enable_audio: true` requires `mode: pro`.
  Model `3.0` defaults to audio enabled; set `enable_audio: false` to disable.

- `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts for multi-shot storytelling (v3 only).
  Maximum length: 2500 characters per shot.
  Minimum 2 shots required. Cannot be used together with `prompt` or `duration`.

- `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds.
  Each shot must have both prompt and duration. Total duration must be 3-15 seconds.
  Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`).

- `maxJobs` is optional, range from `1` to `50`.   
  Specifies the maximum number of concurrent jobs. 
  
- `replyUrl` is optional, a callback URL to receive generation progress and result.   
  See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

**200**
**200 OK**
```json
{
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_txt2video_hq",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_txt2video_hq",
      "inputs": [],
      "arguments": [
        {
          "name": "prompt",
          "value": "A majestic mountain landscape with snow-capped peaks and flowing rivers"
        },
        {
          "name": "negative_prompt",
          "value": "people, buildings, text, low quality"
        },
        {
          "name": "cfg",
          "value": "0.5"
        },
        {
          "name": "duration",
          "value": "5"
        },
        {
          "name": "kling_version",
          "value": "1.6"
        },
        {
          "name": "aspect_ratio",
          "value": "16:9"
        }
      ],
      "extraArgs": {},
      "callbackPayloads": [],
      "scene": "NORMAL_CREATION"
    },
    "favored": false,
    "deleted": false,
    "viewed": false,
    "createTime": 1745376611075,
    "updateTime": 1745376611075
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": "",
  "limitation": {
    "type": "m2v_txt2video_hq",
    "remaining": 10000,
    "limit": 10000
  },
  "userPoints": {
    "points": [],
    "total": 0
  },
  "userTickets": {
    "ticket": []
  },
  "editProject": null
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**500**
**500 Internal Server Error**

Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text.

```json
{
  "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)",
  "message": "Service busy (CM_EXT.POther)"
}
```

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    task: {
        id: number
        userId: number
        type: string
        scene: string
        status: number
        status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
        status_final: boolean
        taskInfo: {
            type: string
            inputs: Array<{
                name: string
                inputType: string
                token: string | null
                blobStorage: any | null
                url: string
                cover: string | null
                fromWorkId: number | null
            }>
            arguments: Array<{
                name: string
                value: string
            }>
            extraArgs: Record<string, any>
            callbackPayloads: any[]
            scene: string
        }
        favored: boolean
        deleted: boolean
        viewed: boolean
        createTime: number
        updateTime: number
        viewTime: number
    }
    works: Array<any>
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    message: string
    error: string
    limitation: {
        type: string
        remaining: number
        limit: number
    }
    userPoints: {
        points: Array<{
            orderId: string
            type: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
        total: number
    }
    userTickets: {
        ticket: Array<{
            orderId: string
            type: string
            packageType: string
            amount: number
            balance: number
            startTime: number
            endTime: number
        }>
    }
    editProject: any | null
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/kling/videos/text2video" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "user@example.com",
     "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers",
     "negative_prompt": "people, buildings, text, low quality",
     "model_name": "kling-v1-6",
     "aspect_ratio": "16:9",
     "mode": "pro"
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/videos/text2video"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    prompt: "A majestic mountain landscape with snow-capped peaks and flowing rivers",
    negative_prompt: "people, buildings, text, low quality",
    model_name: "kling-v1-6",
    aspect_ratio: "16:9",
    mode: "pro"
  })
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/videos/text2video"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers",
    "negative_prompt": "people, buildings, text, low quality",
    "model_name": "kling-v1-6",
    "aspect_ratio": "16:9",
    "mode": "pro"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/start-here/setup-midjourney ===
Document URL: https://useapi.net/docs/start-here/setup-midjourney
# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/midjourney.svg"> Setup Midjourney
<small>December 2023 (January 14, 2026)</small>

## Table of contents
<small>Approximately 10 minutes to complete setup steps.</small>  

---
> This is the setup guide for [Midjourney API](/docs/api-midjourney-v3). An active [Midjourney](https://www.midjourney.com) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work.

Please review our Midjourney [Q&A](/docs/questions-and-answers#how-to-avoid-midjourney-bans) section before proceeding. Since the original release back in 2023, we have compiled a list of helpful hints that will help you avoid Midjourney bans.

If you're located outside of North America we strongly suggest using [Opera](https://www.opera.com/) with `VPN` option turned on and VPN region set to Americas to avoid Discord triggering your account tokens reset along with password reset.

## Create Discord account

You need a [Discord](https://discord.com) account to interact with [Midjourney Discord Bot](https://discord.com/discovery/applications/936929561302675456). Create a [new account](https://discord.com/register) if you don't have one already.

Please note that even if you have an existing Discord account, we **strongly** recommend creating a separate Discord account specifically designated for use with the useapi.net API.

Brand new/fresh Discord accounts have a higher chance of being banned when running high Midjourney generation loads. Consider purchasing aged Discord accounts (2-3 years old) from marketplaces like [z2u.com](https://www.z2u.com/) for around $1-3 each. Aged accounts are significantly less likely to trigger automated bans.

## Purchase Midjourney subscription

Follow the [official instructions](https://docs.midjourney.com/docs/plans) to purchase a subscription. We suggest starting with the **Basic Plan**. You can always upgrade later, once you are satisfied with initial testing and ready to scale up.

It is **important** not to use the Midjourney account set up for API access for any purposes other than its intended use, such as executing `/imagine` or any other Midjourney commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the Midjourney account, including the number of currently active executions. Using it for other activities may cause the API to function incorrectly.

Please skip this step if you already have a Midjourney subscription.

## Locate Midjourney Direct Messages `channel`

The Midjourney Direct Messages channel value is not required for setup and is only needed for reference.

Select Direct Messages (DMs) in Discord <span style="color: red;">`1`</span>:  
* Locate Midjourney Bot <span style="color: red;">`2`</span>.  
* Copy the value of the channel from the URL <span style="color: red;">`3`</span>.   
  This is your `channel`, the API will use this channel to communicate with the Midjourney Discord bot.

If you have trouble locating the Midjourney Direct Messages channel, refer to the official [documentation](https://docs.midjourney.com/hc/en-us/articles/32637339216013-Discord-Direct-Messages).

![](/assets/images/mj_setup_1.png)

## Locate Discord `token`

Select Direct Messages (DMs) in Discord <span style="color: red;">`1`</span>.

Refresh your browser page.

Once the page is fully loaded, open [Developer Tools](https://developer.chrome.com/docs/devtools) via [keyboard shortcuts](https://developer.chrome.com/docs/devtools/shortcuts): Mac `Command+Option+I` or Windows `F12` or `Control+Shift+I`.

Select Developer Tools » Network <span style="color: red;">`2`</span>:  
* Make sure that `All` or `Fetch/XHR` is selected <span style="color: red;">`3`</span>.  
* Type `/messages` in the filter box <span style="color: red;">`4`</span> and hit Enter.  
* Select the first `messages?limit...` HTTP call entry as shown below <span style="color: red;">`5`</span>, and click on that entry.  
* Select the "Headers" tab <span style="color: red;">`6`</span>.  
* Locate Request Headers » Authorization <span style="color: red;">`7`</span> and copy its value.   
  This is your `token`.  

![](/assets/images/mj_setup_2.png)

If you have trouble locating the Discord token, there are many tutorials describing how to obtain Discord tokens. Please refer to the following links below for additional guidance:
- [How to Find Your Discord Token](https://discordhelp.net/discord-token)
- [How To Get Your Discord Token](https://pcstrike.com/how-to-get-discord-token/)
- [How to get Discord Token](https://linuxhint.com/get-discord-token/)

Keep in mind that anyone with a Discord token can have **full access** to your Discord account, so please keep it **safe** and **secure**. To reset your Discord token, simply change your Discord password.

## Add account

<script>

async function verifyChannel() {
    const discord = document.getElementById(`channel-discord`)?.value;
    const channel = document.getElementById(`channel-channel`)?.value;

    if (!discord) {
      document.getElementById(`channel-discord`).classList.add('input-error');
      document.getElementById(`channel-discord`).focus();
      return;
    } else {
      document.getElementById(`channel-discord`).classList.remove('input-error');
    }

    if (!channel) {
      document.getElementById(`channel-channel`).classList.add('input-error');
      document.getElementById(`channel-channel`).focus();
      return;
    } else {
      document.getElementById(`channel-channel`).classList.remove('input-error');
    }

    const data = {
        method: 'GET',
        headers: {
          'Authorization': `${discord}`,
          'Content-Type': 'application/json'
        }
      };

      const url=`https://discord.com/api/v10/channels/${channel}`;

      await apiExecute(url, 'channel', data);
}
</script>

Once all the above steps are completed, you should have the following:
- Discord `token`
- Midjourney Direct Messages `channel` (the channel value is not required for setup and is only needed for reference).

Use the form below to add your Midjourney account. You should receive response `201` (new account) or `200` (existing account updated) if successful. You can also use [POST /accounts](/docs/api-midjourney-v3/post-midjourney-accounts) directly.

<script>
  async function apiTestAccountStudio() {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let discord = document.getElementById(`post-accounts-token`)?.value;

      data.body = JSON.stringify({ discord, maxJobs: 3, maxImageJobs: 3, maxVideoJobs: 3 });

      await apiExecute(`https://api.useapi.net/v3/midjourney/accounts`, 'post-accounts', data);
  }
</script>

<form id="post-accounts" onsubmit="apiTestAccountStudio(); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-token"><span>Discord token</span>
        <input id="post-accounts-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
    </div>
    <button id="post-accounts-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/captcha-solver ===
Document URL: https://useapi.net/docs/api-midjourney-v3/captcha-solver
# CAPTCHA Solver
<small>December 8, 2025</small>

---

Our API includes an **automated CAPTCHA solver** at no additional cost with your subscription.

## What Triggers CAPTCHA Challenges

Midjourney Discord bot may present CAPTCHA challenges when it detects unusual activity patterns:

- Too many generations in a short period of time
- Recently created Discord accounts are more likely to be challenged
- Active connections from different geographical locations for the same account

## How It Works

When a CAPTCHA is detected:

1. The generation that triggered the CAPTCHA fails with a `596` error. The Midjourney account is locked and updated with an error message explaining that a CAPTCHA was detected. All subsequent API calls for this account will return `596` until the CAPTCHA solver unlocks the account or you manually resolve it via [POST /accounts/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset)
2. You receive a notification email immediately
3. The CAPTCHA solver is triggered automatically
4. A second email is sent either:
   - Confirming the solver successfully cleared the CAPTCHA and unlocked the account, or
   - Asking you to solve it manually (rare cases)

The entire process takes 60-90 seconds. Based on our in-house testing, we expect the success rate to be close to 100%.

👉 We strongly recommend setting your Discord account language to **English**. Our CAPTCHA solver is primarily tested with English and may not work as reliably with other languages.

## Important: Preventing Excessive CAPTCHAs

While our CAPTCHA solver will handle challenges automatically, **frequent CAPTCHAs indicate you are pushing the account too hard**. Continued aggressive usage patterns may lead to **permanent account bans** by Discord/Midjourney.

To avoid problems:

### Add More Accounts

If you're hitting CAPTCHAs frequently, consider adding more Midjourney accounts to spread the load. Our API supports [multiple accounts](/docs/api-midjourney-v3/setup-multiple-midjourney-accounts) with automatic load balancing.

### Handle 596 Errors Gracefully

When you receive a `596` error response, it indicates account issues (often CAPTCHA-related). Consider a 10-15 minute cooloff period before retrying. If you have multiple accounts configured, our load balancer will automatically switch to a different one.

### Recommended Practices

- Spread load across multiple accounts
- Add random delays between generations
- If you run mostly `--relax` generations, execute `--fast` once in a while

## No Additional Cost

The CAPTCHA solver is **included free** with your useapi.net subscription. There are no per-solve charges or hidden fees.

=== URL: https://useapi.net/docs/api-midjourney-v3/delete-midjourney-accounts-channel ===
Document URL: https://useapi.net/docs/api-midjourney-v3/delete-midjourney-accounts-channel
## Delete Channel Configuration
<small>October 27, 2025</small>

---

Delete a configured Midjourney channel. This removes the channel from your account configuration.

**Warning:** This action cannot be undone. All running jobs for this channel will continue, but you won't be able to create new jobs until you reconfigure the channel.
> **https://api.useapi.net/v3/midjourney/accounts/`channel`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `channel` is **required**. The Discord channel ID to delete.

### Responses

**204**
**204 No Content**

Channel deleted successfully.

**No Content** (empty response body)

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Channel not found or not configured.

**No Content** (empty response body)

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/1234567890123456789"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const channelId = '1234567890123456789';

const response = await fetch(`https://api.useapi.net/v3/midjourney/accounts/${channelId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (response.status === 204) {
  console.log('Channel deleted successfully');
} else {
  console.error('Failed to delete channel:', response.status);
}
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
channel_id = '1234567890123456789'

response = requests.delete(
    f'https://api.useapi.net/v3/midjourney/accounts/{channel_id}',
    headers={'Authorization': f'Bearer {token}'}
)

if response.status_code == 204:
    print('Channel deleted successfully')
else:
    print(f'Failed to delete channel: {response.status_code}')
```

### Try It

<script>
  async function apiExecuteDeleteAccount() {
    const tokenElement = document.getElementById('input-token');
    const channelElement = document.getElementById('input-channel');

    const data = {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    const channel = channelElement.value?.trim();
    const url = `https://api.useapi.net/v3/midjourney/accounts/${channel}`;

    await apiExecute(url, 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (required - Discord channel ID)</small></span>
        <input id="input-channel" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteAccount()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/delete-midjourney-jobs-jobid ===
Document URL: https://useapi.net/docs/api-midjourney-v3/delete-midjourney-jobs-jobid
## Cancel Running Job
<small>October 27, 2025</small>

---

Cancel a running job by ID.

**Only running jobs can be cancelled:**
   - Status must be: `created`, `started`, or `progress`
   - Cannot cancel: `completed`, `failed`, or `moderated` jobs

**Job will be marked as failed:**
   - Status updated to `failed`
   - Error message: "Job cancelled by user"
   - Job removed from running jobs list and will not longer returned by [GET /jobs](/docs/api-midjourney-v3/get-midjourney-jobs)

**Discord cleanup:**
   - The API does not delete the Discord message
   - Message remains in your Midjourney DM (direct messages) channel
> **https://api.useapi.net/v3/midjourney/jobs/`jobid`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobid` is **required**. The job ID to cancel.

### Responses

**204**
**204 No Content**

Job cancelled successfully.

**No Content** (empty response body)

The job status has been updated to `failed` and removed from running jobs list.

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Job not found.

```json
{
  "error": "Job not found"
}
```

**410**
**410 Gone**

Job expired (older than 62 days).

```json
{
  "error": "Job j1023... has expired"
}
```

### Examples

**Curl**
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney"
```

**JavaScript**
``` javascript
const jobId = 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney';

const response = await fetch(
  `https://api.useapi.net/v3/midjourney/jobs/${jobId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  }
);

if (response.status === 204) {
  console.log('Job cancelled successfully');
} else {
  console.error('Failed to cancel job:', response.status);
}
```

**Python**
``` python
import requests

job_id = 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney'

response = requests.delete(
    f'https://api.useapi.net/v3/midjourney/jobs/{job_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

if response.status_code == 204:
    print('Job cancelled successfully')
else:
    print(f'Failed to cancel job: {response.status_code}')
```

### Try It

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token</span>
        <input id="input-token" type="text" class="input-element" required>
      </label>
      <label for="input-jobId"><span>jobId</span>
        <input id="input-jobId" type="text" class="input-element" required>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteJob()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

<script>
  async function apiExecuteDeleteJob() {
    const jobId = document.getElementById('input-jobId').value;
    const url = `https://api.useapi.net/v3/midjourney/jobs/${jobId}`;
    await apiExecute(url, 'input', {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${document.getElementById('input-token').value}`
      }
    });
  }
</script>

=== URL: https://useapi.net/docs/api-midjourney-v3/demo ===
Document URL: https://useapi.net/docs/api-midjourney-v3/demo

<iframe src="/assets/midjourney-v3/index.html" style="width: 100%; height: calc(100vh - 100px); border: none;" title="Midjourney API v3 Live Demo"></iframe>

=== URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts-channel ===
Document URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts-channel
## Get Channel Configuration
<small>October 27, 2025</small>

---

Get configuration details for a specific Midjourney channel.
> **https://api.useapi.net/v3/midjourney/accounts/`channel`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `channel` is **required**. The Discord channel ID to query.

### Responses

**200**
**200 OK**

Channel configuration found and returned.

```json
{
  "discord": "MTI...xyz",
  "channel": "1234567890123456789",
  "maxJobs": 3,
  "maxImageJobs": 3,
  "maxVideoJobs": 3,
  "replyUrl": "https://your-server.com/webhook"
}
```

**Note:** Discord tokens are redacted for security (first 3 and last 3 characters shown).

If a channel has an `error` field, it requires attention:
- Use [POST /accounts/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset) to clear the error
- Check your Discord account for moderation messages or CAPTCHA challenges

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Channel not found or not configured.

**No Content** (empty response body)

### Model
```typescript
{
  discord: string          // Discord token (redacted)
  channel: string          // Discord channel ID
  maxJobs: number          // Max total concurrent jobs
  maxImageJobs: number     // Max concurrent image jobs
  maxVideoJobs: number     // Max concurrent video jobs
  replyUrl?: string        // Webhook URL for callbacks
  error?: string           // Error message (if channel has issues)
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/1234567890123456789"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const channelId = '1234567890123456789';

const response = await fetch(`https://api.useapi.net/v3/midjourney/accounts/${channelId}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const channelConfig = await response.json();
console.log('Channel config:', channelConfig);
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
channel_id = '1234567890123456789'

headers = {'Authorization': f'Bearer {token}'}

response = requests.get(
    f'https://api.useapi.net/v3/midjourney/accounts/{channel_id}',
    headers=headers
)

print('Channel config:', response.json())
```

### Try It

<script>
  async function apiExecuteGetAccountsChannel() {
    const tokenElement = document.getElementById('input-token');
    const channelElement = document.getElementById('input-channel');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute(`https://api.useapi.net/v3/midjourney/accounts/${channelElement.value}`, 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (required)</small></span>
        <input id="input-channel" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetAccountsChannel()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts ===
Document URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts
## List All Configured Channels
<small>October 27, 2025</small>

---

List all configured Midjourney channels for your account.

**To get a specific channel:** Use [GET /accounts/:channel](/docs/api-midjourney-v3/get-midjourney-accounts-channel).
> **https://api.useapi.net/v3/midjourney/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

Returns a map of all configured channels, keyed by channel ID.

```json
{
  "1234567890123456789": {
    "discord": "MTI...xyz",
    "channel": "1234567890123456789",
    "maxJobs": 3,
    "maxImageJobs": 3,
    "maxVideoJobs": 3,
    "replyUrl": "https://your-server.com/webhook"
  },
  "9876543210987654321": {
    "discord": "ABC...def",
    "channel": "9876543210987654321",
    "maxJobs": 5,
    "maxImageJobs": 5,
    "maxVideoJobs": 3,
    "error": "Pending mod message"
  }
}
```

**Note:** Discord tokens are redacted for security (first 3 and last 3 characters shown).

If a channel has an `error` field, it requires attention:
- Use [POST /accounts/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset) to clear the error
- Check your Discord account for moderation messages or CAPTCHA challenges

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

No channels configured.

**No Content** (empty response body)

### Model
```typescript
// Map of channel ID to channel configuration
{
  [channelId: string]: {
    discord: string          // Discord token (redacted)
    channel: string          // Discord channel ID
    maxJobs: number          // Max total concurrent jobs
    maxImageJobs: number     // Max concurrent image jobs
    maxVideoJobs: number     // Max concurrent video jobs
    replyUrl?: string        // Webhook URL for callbacks
    error?: string           // Error message (if channel has issues)
  }
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';

const response = await fetch('https://api.useapi.net/v3/midjourney/accounts', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const channels = await response.json();
console.log('Configured channels:', channels);
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
headers = {'Authorization': f'Bearer {token}'}

response = requests.get('https://api.useapi.net/v3/midjourney/accounts', headers=headers)
print('All channels:', response.json())
```

### Try It

<script>
  async function apiExecuteGetAccounts() {
    const tokenElement = document.getElementById('input-token');

    const data = {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`
      }
    };

    await apiExecute('https://api.useapi.net/v3/midjourney/accounts', 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetAccounts()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-jobs-jobid ===
Document URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-jobs-jobid
## Retrieve Job Status and Results
<small>October 27, 2025</small>

---
> **https://api.useapi.net/v3/midjourney/jobs/`jobid`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `jobid` is **required**. The job ID to query.

### Responses

**200**
**200 OK**

Job found and returned successfully.

```json
{
  "jobid": "j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney",
  "verb": "imagine",
  "status": "completed",
  "created": "2025-10-23T14:15:20.123Z",
  "updated": "2025-10-23T14:16:45.789Z",
  "request": {
    "prompt": "a cat in a hat --ar 16:9"
  },
  "response": {
    "content": "**a cat in a hat** - <@user> (100%) (fast)",
    "progress_percent": 100,
    "attachments": [
      {
        "url": "https://cdn.discordapp.com/attachments/.../image.png",
        "proxy_url": "https://media.discordapp.net/...",
        "filename": "image.png",
        "width": 1920,
        "height": 1080
      }
    ],
    "buttons": ["U1", "U2", "U3", "U4", "V1", "V2", "V3", "V4", "🔄"],
    "imageUx": [
      {"id": 1, "url": "https://cdn.midjourney.com/.../0_0.jpeg"},
      {"id": 2, "url": "https://cdn.midjourney.com/.../0_1.jpeg"},
      {"id": 3, "url": "https://cdn.midjourney.com/.../0_2.jpeg"},
      {"id": 4, "url": "https://cdn.midjourney.com/.../0_3.jpeg"}
    ],
    "children": {},
    "executeOnce": {}
  }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**404**
**404 Not Found**

Job not found.

```json
{
  "error": "Job not found"
}
```

**410**
**410 Gone**

Job expired (older than 62 days).

```json
{
  "error": "Job j1023... has expired"
}
```

### Model
```typescript
{
  // Top-level metadata (always returned to customer)
  jobid: string
  verb: 'imagine' | 'button' | 'describe' | 'blend' | 'seed' | 'info' |
        'fast' | 'relax' | 'turbo' | 'variability' | 'remix'
  jobType?: 'image' | 'video'
  status: 'created' | 'started' | 'progress' | 'completed' | 'failed' | 'moderated'
  created: string  // ISO 8601 timestamp
  updated?: string  // ISO 8601 timestamp
  error?: string
  errorDetails?: string
  code?: number // HTTP response status code

  // Original request parameters (returned to customer)
  request: {
    prompt?: string
    button?: 'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' |
             'V3' | 'V4' | '⬅️' | '➡️' | '⬆️' | '⬇️' |
             'Vary (Region)' | 'Vary (Strong)' | 'Vary (Subtle)' | 'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Upscale (2x)' |
             'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' | 'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' |
             'Redo Upscale (Creative)' | 'Make Square' | 'Make Variations' | 'Remaster' | 'Custom Zoom' | '🔄' |
             'Animate (Low motion)' | 'Animate (High motion)' | 'Extend (Low motion)' | 'Extend (High motion)'
    mask?: string
    describeUrl?: string
    blendUrls?: string[]
    blendDimensions?: 'Portrait' | 'Square' | 'Landscape'
    jobId?: string            // Parent job ID for button/seed commands
    channel?: string
    maxJobs?: number
    replyUrl?: string
    replyRef?: string
    stream?: boolean
  }

  // Discord response (returned to customer when available)
  // NOTE: This is essentially Discord's message format
  response?: {
    id?: string
    content?: string
    timestamp?: string
    progress_percent?: number     // Numeric progress (0-100) extracted from content
    settings?: {                  // Settings state for /settings, /remix, /variability, /info commands
      // Model version
      version?: string            // e.g., "7", "6.1", "niji 6", "default"
      // Stylization
      stylize?: number            // Stylization value: 50, 100, 250, 750
      raw?: boolean               // RAW mode
      // Personalization
      personalization?: boolean   // Personalization mode
      // Privacy
      public?: boolean            // Public mode (true) or Private mode (false)
      // Remix and Variation
      remix?: boolean             // Remix mode
      variability?: boolean       // Variation mode: true = High/Strong, false = Low/Subtle
      // Speed modes
      relax?: boolean             // Relax mode
      fast?: boolean              // Fast mode
      turbo?: boolean             // Turbo mode
      // Suffix
      suffix?: string             // Current suffix applied to prompts (e.g., " --v 7 --s 250")
    }
    // Available buttons (populated at job completion)
    buttons?: Array<'U1' | 'U2' | 'U3' | 'U4' | 
                    'V1' | 'V2' | 'V3' | 'V4' | 
                    '⬅️' | '➡️' | '⬆️' | '⬇️' |
                    'Vary (Region)' | 'Vary (Strong)' | 'Vary (Subtle)' | 
                    'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Upscale (2x)' |
                    'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' | 
                    'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' |
                    'Redo Upscale (Creative)' | 'Make Square' | 'Make Variations' | 
                    'Remaster' | 'Custom Zoom' | '🔄' |
                    'Animate (Low motion)' | 'Animate (High motion)' | 
                    'Extend (Low motion)' | 'Extend (High motion)'>   
    videoUx?: Array<{ id: number, url: string }>  // Video upscale URLs (populated at job completion)
    imageUx?: Array<{ id: number, url: string }>  // Image upscale URLs (populated at job completion)
    executeOnce?: Partial<Record<'U1' | 'U2' | 'U3' | 'U4', string>>  // ExecuteOnce button tracking
    children?: Record<string, { button: string, messageId: string }>  // Child jobs tracking
    attachments?: Array<{
      id: string
      filename: string
      url: string
      proxy_url: string
      size: number
      width?: number
      height?: number
      content_type?: string
    }>
    embeds?: Array<{
      title?: string
      description?: string
      color?: number
    }>
    components?: Array<{
      type: number
      components: Array<{
        type: number
        style: number
        label?: string
        emoji?: { name: string }
        custom_id?: string
        disabled?: boolean
        url?: string
      }>
    }>
  }
}
```

##### `response` object

The `response` object is an enhanced version of a Discord message. All standard Discord message fields are included by default. See [Discord Message Object](https://discord.com/developers/docs/resources/message#message-object) for reference.

- `content` - Midjourney message text. Contains useful information for settings jobs (current settings display) and moderation events (ban/CAPTCHA warnings).
- `progress_percent` - Numeric progress (0-100) extracted from content
- `imageUx` / `videoUx` - Array of individual media assets from the grid. Each contains `id` (1-4) and `url` (direct CDN link from `https://cdn.midjourney.com`). Use [GET /proxy/cdn-midjourney](/docs/api-midjourney-v3/get-proxy-cdn-midjourney) to retrieve these assets via useapi.net proxy.
- `attachments` - Discord attachments array with full metadata (`url`, `proxy_url`, `width`, `height`, `filename`)
- `settings` - Settings state returned by settings commands. Different commands return different subsets:
  - `/settings` - Returns complete settings: `version`, `stylize`, `raw`, `personalization`, `public`, `remix`, `variability`, `turbo`, `fast`, `relax`, `suffix`
  - `/info`, `/fast`, `/relax`, `/turbo` - Returns speed modes only: `fast`, `relax`, `turbo`
  - `/remix` - Returns `remix` only
  - `/variability` - Returns `variability` only
- `executeOnce` - ExecuteOnce button tracking (U1-U4 buttons can only be executed once)
- `children` - Child jobs tracking

For image/video jobs, use `imageUx`/`videoUx` to access individual grid cells, or `attachments[0]` for the complete grid image. The `proxy_url` in attachments may be preferred as it provides Discord's CDN caching.

##### Job Statuses • `status`

| Status | Description |
|--------|-------------|
| `created` | Job created, not yet started |
| `started` | Job started processing |
| `progress` | Job in progress (check `response.progress_percent`) |
| `completed` | Job finished successfully |
| `failed` | Job failed (see `error`, `errorDetails`, and `code` fields for error code and details) |
| `moderated` | Content moderation (see `error`, `errorDetails`, `code` fields, and check `response.embeds` for moderation details) |

##### Job Types • `jobType`

| Type | Description | Endpoints |
|------|-------------|-----------|
| `image` | Image generation jobs | **imagine** (without `--video` flag), **blend**, **button** (U1-U4, V1-V4, variations, upscales, zoom, etc.) |
| `video` | Video generation jobs | **imagine** (with `--video` flag), **button** (Animate Low/High motion, Extend Low/High motion, or any button on a video parent job) |
| *undefined* | Settings and info commands (no jobType tracking) | **describe**, **seed**, **settings**, **info**, **fast**, **relax**, **turbo**, **remix**, **variability** |

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney"
```

**JavaScript**
``` javascript
const response = await fetch(
  'https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
  {
    headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
  }
);

const job = await response.json();
console.log('Job status:', job.status);
console.log('Job response:', job.response);
```

**Python**
``` python
import requests

response = requests.get(
    'https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

job = response.json()
print('Job status:', job['status'])
print('Job response:', job.get('response'))
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteGetJob() {
    const jobId = document.getElementById('input-jobId').value;
    const url = `https://api.useapi.net/v3/midjourney/jobs/${jobId}`;
    await apiExecute(url, 'input', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${document.getElementById('input-token').value}`
      }
    });

    const responseJson = document.getElementById('input-response-json').innerText;
    if (responseJson) {
      try {
        const jobData = JSON.parse(responseJson);
        if (jobData.status === 'completed') {
          displayMediaLinks(jobData, 'input');
        }
      } catch (e) {}
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token</span>
        <input id="input-token" type="text" class="input-element" required>
      </label>
      <label for="input-jobId"><span>jobId</span>
        <input id="input-jobId" type="text" class="input-element" required>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetJob()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-jobs ===
Document URL: https://useapi.net/docs/api-midjourney-v3/get-midjourney-jobs
## List Running Jobs
<small>October 27, 2025</small>

---

List all currently running jobs for your account.
> **https://api.useapi.net/v3/midjourney/jobs**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Responses

**200**
**200 OK**

List of running jobs returned successfully.

Returns only jobs with status `created`, `started`, or `progress`. Completed and failed jobs are not included. Use [DELETE /jobs/`jobid`](/docs/api-midjourney-v3/delete-midjourney-jobs-jobid) to cancel a running job by ID.

```json
{
  "total": 2,
  "images": 2,
  "videos": 0,
  "channels": {
    "1234567890123456789": {
      "total": 2,
      "images": 2,
      "videos": 0,
      "maxJobs": 3,
      "maxImageJobs": 3,
      "maxVideoJobs": 3,
      "jobs": [
        {
          "jobId": "j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney",
          "channel": "1234567890123456789",
          "jobType": "image",
          "created": "2025-10-23T14:15:20.123Z",
          "elapsed": "00:32"
        },
        {
          "jobId": "j1023141525987654321i-u12345-c1234567890123456789-bot:midjourney",
          "channel": "1234567890123456789",
          "jobType": "image",
          "created": "2025-10-23T14:15:25.987Z",
          "elapsed": "00:27"
        }
      ]
    }
  }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

### Model
```typescript
{
  total: number         // Total number of running jobs
  images: number        // Number of running image jobs
  videos: number        // Number of running video jobs
  channels: Record<string, {
    total: number       // Total jobs in this channel
    images: number      // Image jobs in this channel
    videos: number      // Video jobs in this channel
    maxJobs: number     // Maximum concurrent jobs allowed
    maxImageJobs: number // Maximum concurrent image jobs allowed
    maxVideoJobs: number // Maximum concurrent video jobs allowed
    jobs: Array<{
      jobId: string     // Job ID
      channel: string   // Channel ID
      jobType: 'image' | 'video'  // Job type
      created: string   // ISO 8601 timestamp
      elapsed: string   // Elapsed time (mm:ss)
    }>
  }>
}
```

### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs"
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const result = await response.json();
console.log(`${result.total} jobs running (${result.images} images, ${result.videos} videos)`);

for (const [channelId, channelData] of Object.entries(result.channels)) {
  console.log(`Channel ${channelId}: ${channelData.total} jobs`);
  for (const job of channelData.jobs) {
    console.log(`  ${job.jobId}: ${job.jobType} (${job.elapsed})`);
  }
}
```

**Python**
``` python
import requests

response = requests.get(
    'https://api.useapi.net/v3/midjourney/jobs',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

result = response.json()
print(f"{result['total']} jobs running ({result['images']} images, {result['videos']} videos)")

for channel_id, channel_data in result['channels'].items():
    print(f"Channel {channel_id}: {channel_data['total']} jobs")
    for job in channel_data['jobs']:
        print(f"  {job['jobId']}: {job['jobType']} ({job['elapsed']})")
```

### Try It

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token</span>
        <input id="input-token" type="text" class="input-element" required>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetJobs()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

<script>
  async function apiExecuteGetJobs() {
    const url = 'https://api.useapi.net/v3/midjourney/jobs';
    await apiExecute(url, 'input', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${document.getElementById('input-token').value}`
      }
    });
  }
</script>

=== URL: https://useapi.net/docs/api-midjourney-v3/get-proxy-cdn-midjourney ===
Document URL: https://useapi.net/docs/api-midjourney-v3/get-proxy-cdn-midjourney
## Proxy asset retrieval from https://cdn.midjourney.com
<small>October 27, 2025</small>

---

This endpoint allows you to fetch images and videos from `https://cdn.midjourney.com/` through the useapi.net proxy. Use it to retrieve `imageUx` and `videoUx` URLs returned by
[GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) or any other assets hosted on `https://cdn.midjourney.com/`.

The Midjourney CDN requires standard browser headers—specifically the `User-Agent` header—to serve assets. Without it, Cloudflare will block the request. This proxy endpoint adds these headers automatically.

##### Alternative: Direct CDN Access

You can skip the proxy and fetch assets directly from `https://cdn.midjourney.com/` by including the necessary headers:

**Curl**
``` bash
curl "https://cdn.midjourney.com/example-image.jpg" \
     -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36" \
     -H "Accept: */*" \
     -H "Accept-Encoding: gzip, deflate, br" \
     -H "Connection: keep-alive" \
     --output image.jpg
```

**JavaScript**
``` javascript
const cdnUrl = "https://cdn.midjourney.com/example-image.jpg";

const headers = new Headers();
headers.set('User-Agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36');
headers.set('Accept', '*/*');
headers.set('Accept-Encoding', 'gzip, deflate, br');
headers.set('Connection', 'keep-alive');

const response = await fetch(cdnUrl, { headers });
const blob = await response.blob();

// Save to file (Node.js)
const fs = require('fs');
const buffer = await blob.arrayBuffer();
fs.writeFileSync('image.jpg', Buffer.from(buffer));
```

**Python**
``` python
import requests

cdnUrl = "https://cdn.midjourney.com/example-image.jpg"

headers = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36',
    'Accept': '*/*',
    'Accept-Encoding': 'gzip, deflate, br',
    'Connection': 'keep-alive'
}

response = requests.get(cdnUrl, headers=headers)

# Save image/video content
with open('image.jpg', 'wb') as f:
    f.write(response.content)
```

**Note:** The `User-Agent` header is critical—without it, Cloudflare will block your request.

---
> **https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=`https://cdn.midjourney.com/…`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameter
- `cdnUrl` is **required** and must be a valid asset URL starting with `https://cdn.midjourney.com/`

##### Responses

**200**

**200 OK**

Returns the proxied content from the Midjourney CDN with appropriate headers.

**400**
**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**403**
**403 Forbidden**

Cloudflare may occasionally block requests even with proper headers. This is typically temporary and can be resolved with retry logic.

**Recommendation:** Implement retry logic with exponential backoff when encountering 403 errors, or better yet, implement your own direct CDN access using the headers shown in the "Alternative: Direct CDN Access" section above for greater control and reliability.

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=https://cdn.midjourney.com/example-image.jpg"
```

**JavaScript**
``` javascript
const cdnUrl = "https://cdn.midjourney.com/example-image.jpg";
const apiUrl = `https://api.useapi.net/v1/proxy/cdn-midjourney/`;
const api_token = "API token";
const response = await fetch(`${apiUrl}?cdnUrl=${encodeURIComponent(cdnUrl)}`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${api_token}`
    }
});

const result = await response.blob(); // For image/video content
console.log("response", {response, result});
```

**Python**
``` python
import requests
cdnUrl = "https://cdn.midjourney.com/example-image.jpg"
apiUrl = f"https://api.useapi.net/v1/proxy/cdn-midjourney/"
api_token = "API token"
headers = {
    "Authorization": f"Bearer {api_token}"
}

params = {
    "cdnUrl": cdnUrl
}

response = requests.get(apiUrl, headers=headers, params=params)
print(response.status_code, response.headers)

# Save image/video content
with open('image.jpg', 'wb') as f:
    f.write(response.content)
```

=== URL: https://useapi.net/docs/api-midjourney-v3 ===
Document URL: https://useapi.net/docs/api-midjourney-v3

# <img style="height:2em;vertical-align: middle;" src="/assets/images/midjourney.svg">Midjourney API v3
<small>October 27, 2025 (December 8, 2025)</small>

This is the next-generation [experimental](/docs/legal) API for the [Midjourney Discord Bot](https://discord.com/invite/midjourney) by [Midjourney](https://www.midjourney.com).

See [What's New in v3](/docs/api-midjourney-v3/what-new) for new features and migration guide.

The **entire** Midjourney Discord Bot functionality is supported, including **video generation**, [seed](https://docs.midjourney.com/docs/seeds) retrieval, [variations mode](https://docs.midjourney.com/docs/variations), [remix mode](https://docs.midjourney.com/docs/remix), and everything else the Midjourney Discord Bot offers.

Our experimental API uses intelligent logic to prevent potential issues with Discord and Midjourney, such as bans, CAPTCHA challenges, or excessive requests. API comes with an automated [CAPTCHA solver](/docs/api-midjourney-v3/captcha-solver) at no additional cost.

We fully support the ability to use multiple Midjourney accounts, complete with automated load balancing.

[Setup Midjourney](/docs/start-here/setup-midjourney)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(January 20, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-midjourney-v3.txt) <small>Feed this to your LLM to build integrations</small>

[Quick Start Guide](/docs/api-midjourney-v3/quick-start)

[Q&A](/docs/questions-and-answers#how-to-avoid-runway-account-suspension)

Articles:
* [16+ AI Image Models: The Showdown](/blog/260309i)
* 🎨 [Live Demo](/assets/midjourney-v3/)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/midjourney_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/midjourney_api</a>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts-reset ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts-reset
## Reset Channel After Moderation
<small>October 27, 2025 (March 3, 2026)</small>

---

Clear error state from a channel configuration. Use this after resolving moderation issues or CAPTCHA challenges in your Discord account.

When the API detects moderation messages or CAPTCHA challenges (596 error), it sets an error state on the channel and sends you an email notification. After clearing the issue in Discord, use this endpoint to reset the channel.
> **https://api.useapi.net/v3/midjourney/accounts/reset/`channel`**

### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Path Parameters

- `channel` is **required**. The Discord channel ID to reset.

##### When to Use This Endpoint

Use this endpoint when:
1. You receive a 596 error (moderation/CAPTCHA detected)
2. You get an email notification about channel issues
3. [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) shows an `error` field for the channel

**Before resetting:**
1. Log into your Discord account
2. Check Midjourney DM for pending moderation messages
3. Complete any CAPTCHA challenges
4. Acknowledge any warnings from Midjourney

**After resolving the issue in Discord:**
- Call this endpoint to clear the error state
- The channel will be available for new jobs

### Responses

**204**
**204 No Content**

Error cleared successfully. Channel is ready for use.

**No Content** (empty response body)

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

Channel not found or not configured.

**No Content** (empty response body)

**596**
**596 Pending mod message**

Returned when the channel has an active ban that has not yet expired, or a permanent ban. Reset is not allowed until the ban expires.

```json
{
  "error": "You have been temporarily blocked from accessing Midjourney.\nYour block ends <t:1772509411:R> (2026-03-03 03:43 UTC)",
  "expiresIn": "2 days 5 hours 30 minutes",
  "code": 596
}
```

For permanent bans, `expiresIn` will be `"permanent"`. Delete this account via [DELETE /accounts/channel](/docs/api-midjourney-v3/delete-midjourney-accounts-channel) and configure a new Discord account.

### Model
```typescript
{ // TypeScript, all fields are optional
  error: string,
  expiresIn: string,
  code: number
}
```

### Examples

**Curl**
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/reset/1234567890123456789"
```

**JavaScript**
``` javascript
const token = 'YOUR_API_TOKEN';
const channelId = '1234567890123456789';

const response = await fetch(
  `https://api.useapi.net/v3/midjourney/accounts/reset/${channelId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

if (response.status === 204) {
  console.log('Channel reset successfully');
} else {
  console.error('Failed to reset channel:', response.status);
}
```

**Python**
``` python
import requests

token = 'YOUR_API_TOKEN'
channel_id = '1234567890123456789'

response = requests.post(
    f'https://api.useapi.net/v3/midjourney/accounts/reset/{channel_id}',
    headers={'Authorization': f'Bearer {token}'}
)

if response.status_code == 204:
    print('Channel reset successfully')
else:
    print(f'Failed to reset channel: {response.status_code}')
```

### Try It

<script>
  async function apiExecuteAccountsReset() {
    const tokenElement = document.getElementById('input-token');
    const channelElement = document.getElementById('input-channel');

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({})
    };

    const channel = channelElement.value?.trim();

    const url = `https://api.useapi.net/v3/midjourney/accounts/reset/${channel}`;

    await apiExecute(url, 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (required - Discord channel ID)</small></span>
        <input id="input-channel" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteAccountsReset()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts
## Configure Midjourney Channel
<small>October 27, 2025</small>

---

Configure your Midjourney Discord channel for API access. The API automatically discovers your Midjourney DM (direct messages) channel from your Discord token.

**Multiple accounts supported:** Configure multiple Discord accounts with automatic load balancing.

**Important:** Same Discord account cannot be used for both v2 and v3 APIs simultaneously. If you have the account configured in v2, [delete it from v2](/docs/api-v2/del-account-midjourney-channel) first before configuring in v3. See [Migration from v2](/docs/api-midjourney-v3/quick-start#migration-from-v2) for details.
> **https://api.useapi.net/v3/midjourney/accounts**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "discord": "Discord token",
  "maxJobs": 3,
  "maxImageJobs": 3,
  "maxVideoJobs": 3,
  "replyUrl": "https://your-server.com/webhook"
}
```

- `discord` is **required**. Your Discord bot token. See [Setup Midjourney](/docs/start-here/setup-midjourney) for details.

- `maxJobs` is optional (default: 3). Maximum total concurrent jobs (all types combined) per channel.
  Must be between 1 and 15. Should match your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison).
  **Important:** Specifying a higher number than your subscription supports will prevent API from functioning properly.

- `maxImageJobs` is optional (default: 3). Maximum concurrent image generation jobs.
  Must be between 1 and 12. Must be ≤ `maxJobs`.

- `maxVideoJobs` is optional (default: 3). Maximum concurrent video generation jobs.
  Must be between 1 and 12. Must be ≤ `maxJobs`.

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events will be POST-ed to this URL as they occur. Maximum length 2048 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

### Responses

**201**
**201 Created**

New channel configuration created successfully.

```json
{
  "discord": "MTI...xyz",
  "channel": "1234567890123456789",
  "maxJobs": 3,
  "maxImageJobs": 3,
  "maxVideoJobs": 3,
  "replyUrl": "https://your-server.com/webhook"
}
```

- `channel` is automatically discovered from your Discord token (Midjourney DM (direct messages) channel ID).

**200**
**200 OK**

Existing channel configuration updated successfully.

```json
{
  "discord": "MTI...xyz",
  "channel": "1234567890123456789",
  "maxJobs": 5,
  "maxImageJobs": 5,
  "maxVideoJobs": 3,
  "replyUrl": "https://your-server.com/webhook"
}
```

**400**
**400 Bad Request**

Validation error (missing/invalid parameters).

```json
{
  "error": "Required parameter discord is missing or empty"
}
```

**401**
**401 Unauthorized**

Invalid API token or Discord token.

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

Subscription expired or insufficient credits.

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**409**
**409 Conflict**

v2 API configuration detected for this channel. v2 and v3 are [incompatible](/docs/api-midjourney-v3/quick-start#prerequisites).

```json
{
  "error": "Legacy v2 Midjourney configuration detected for channel 1234567890123456789. v2 and v3 APIs are incompatible and cannot coexist. Please delete the v2 configuration first: DELETE https://api.useapi.net/v2/midjourney/account/1234567890123456789 (requires Authorization header with your API key). After deletion, you can configure this channel for v3."
}
```

### Model
```typescript
{ // TypeScript, all fields are optional
  discord: string          // Discord token (first 3 and last 3 chars shown)
  channel: string          // Discord channel ID (auto-discovered)
  maxJobs: number          // Max total concurrent jobs
  maxImageJobs: number     // Max concurrent image jobs
  maxVideoJobs: number     // Max concurrent video jobs
  replyUrl?: string        // Webhook URL for callbacks
  error?: string           // Error message (if failed)
}
```

### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -X POST "https://api.useapi.net/v3/midjourney/accounts" \
     -d '{
       "discord": "YOUR_DISCORD_TOKEN",
       "maxJobs": 3,
       "maxImageJobs": 3,
       "maxVideoJobs": 3,
       "replyUrl": "https://your-server.com/webhook"
     }'
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v3/midjourney/accounts';
const token = 'YOUR_API_TOKEN';
const discord = 'YOUR_DISCORD_TOKEN';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    discord: discord,
    maxJobs: 3,
    maxImageJobs: 3,
    maxVideoJobs: 3,
    replyUrl: 'https://your-server.com/webhook'
  })
});

const result = await response.json();
console.log('Channel configured:', result);
```

**Python**
``` python
import requests

apiUrl = 'https://api.useapi.net/v3/midjourney/accounts'
token = 'YOUR_API_TOKEN'
discord = 'YOUR_DISCORD_TOKEN'

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

body = {
    'discord': discord,
    'maxJobs': 3,
    'maxImageJobs': 3,
    'maxVideoJobs': 3,
    'replyUrl': 'https://your-server.com/webhook'
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response.status_code, response.json())
```

### Try It

<script>
  async function apiExecutePostAccounts() {
    const tokenElement = document.getElementById('input-token');

    const data = {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${tokenElement.value}`,
        'Content-Type': 'application/json'
      }
    };

    const payload = {};
    const inputs = document.querySelectorAll('.input-query-param');

    inputs.forEach(input => {
      const id = input.id;
      const value = input.value?.trim();
      if (id.startsWith('input-') && value) {
        const key = id.replace('input-', '');
        
        if (input.type === 'number') {
          payload[key] = parseInt(value, 10);
        } else {
          payload[key] = value;
        }
      }
    });

    data.body = JSON.stringify(payload);

    await apiExecute('https://api.useapi.net/v3/midjourney/accounts', 'input', data);
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-discord"><span>discord<small> (required)</small></span>
        <input id="input-discord" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-maxJobs"><span>maxJobs<small> (1-15)</small></span>
        <input id="input-maxJobs" type="number" min="1" max="15" class="input-element input-query-param">
      </label>
      <label for="input-maxImageJobs"><span>maxImageJobs<small> (1-12)</small></span>
        <input id="input-maxImageJobs" type="number" min="1" max="12" class="input-element input-query-param">
      </label>
      <label for="input-maxVideoJobs"><span>maxVideoJobs<small> (1-12)</small></span>
        <input id="input-maxVideoJobs" type="number" min="1" max="12" class="input-element input-query-param">
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostAccounts()">Go</button>
  </div>
</form>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-blend ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-blend
## Midjourney /blend Command
<small>October 27, 2025 (January 5, 2026)</small>

---

Blend 2-5 images together using Midjourney's [/blend](https://docs.midjourney.com/docs/blend) command.
> **https://api.useapi.net/v3/midjourney/jobs/blend**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "imageUrl_1": "https://example.com/image1.jpg",
  "imageUrl_2": "https://example.com/image2.jpg",
  "imageUrl_3": "https://example.com/image3.jpg",
  "blendDimensions": "Square",
  "stream": true
}
```

### Parameters

- `channel` is optional. Discord channel ID to use. See [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) for configured channels.
  If not provided, API automatically selects available channel with capacity.
  Specify when you want to use a specific configured channel.
  
- `imageUrl_1` and `imageUrl_2` **OR** `imageBlob_1` and `imageBlob_2` are **required**.
  Minimum 2 images, maximum 5 images.
  Can mix URLs and blobs (e.g., `imageUrl_1` + `imageBlob_2`).
  Cannot specify both URL and blob for same number (e.g., both `imageUrl_1` and `imageBlob_1`).
  Maximum file size: 10 MB per image (applies to both URL content and blob uploads).

- `imageUrl_3`, `imageUrl_4`, `imageUrl_5` are optional.
  Maximum file size: 10 MB per image.

- `imageBlob_3`, `imageBlob_4`, `imageBlob_5` are optional.
  Maximum file size: 10 MB per image.

- `blendDimensions` is optional. One of: `Portrait`, `Square`, `Landscape`.
  Default: `Square`.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

```json
{
    "jobid": "j1024182621211758921i-u12345-c1234567890987654321-bot:midjourney",
    "verb": "blend",
    "jobType": "image",
    "status": "created",
    "created": "2025-10-24T18:26:21.223Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:26:14.578Z",
        "stream": false,
        "blendUrls": [
            "blob_0",
            "blob_1"
        ],
        "blendDimensions": "Portrait"
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "At least 2 images are required for blend"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**429**
**429 Too Many Requests**

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:26:44.331"}

data: {"event":"midjourney_created","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"created","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:26:46.184Z"},"seq":11,"ts":"18:26:46.197"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:26:47.562Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"nonce":"1025182641690580089","mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":null,"content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (Waiting to start)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":14,"ts":"18:26:47.574"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:23.989Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:23.870654+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (35%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","progress_percent":35}},"seq":27,"ts":"18:27:24.053"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:27.113Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:26.896125+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (39%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":340,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765767/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","size":26968,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765767/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","placeholder_version":1,"placeholder":"5wcODQCHdouIZ3f3eI8Iea9n9YxF","id":"1431710767656472767","height":512,"filename":"xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","content_type":"image/webp","content_scan_version":2}],"application_id":"936929561302675456","progress_percent":39}},"seq":29,"ts":"18:27:27.130"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:30.414Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:30.156828+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (47%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":340,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765392/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","size":44286,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765392/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","placeholder_version":1,"placeholder":"6AcSBQCIh3yIaHf4h4o4aPpTpY9W","id":"1431710781409329392","height":512,"filename":"xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","content_type":"image/webp","content_scan_version":2}],"application_id":"936929561302675456","progress_percent":47}},"seq":31,"ts":"18:27:30.442"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:33.551Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:33.255487+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (59%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":340,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765277/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","size":51560,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765277/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","placeholder_version":1,"placeholder":"6AcSBQCId3x4aIf4eIo4aPpitW94","id":"1431710794378121277","height":512,"filename":"xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","content_type":"image/webp","content_scan_version":2}],"application_id":"936929561302675456","progress_percent":59}},"seq":33,"ts":"18:27:33.563"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:38.129Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:36.580758+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (71%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":340,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765456/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","size":54612,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765456/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","placeholder_version":1,"placeholder":"6AcSBQCIh3x4aIf4iIo3aPxiw29X","id":"1431710808341221456","height":512,"filename":"xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","content_type":"image/webp","content_scan_version":2}],"application_id":"936929561302675456","progress_percent":71}},"seq":35,"ts":"18:27:38.143"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"progress","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:39.990Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:26:47.461000+00:00","position":0,"pinned":false,"mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"blend","id":"1431710596566487262"},"id":"1431710602199306372","flags":0,"embeds":[],"edited_timestamp":"2025-10-24T18:27:39.664947+00:00","content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (87%) (relaxed)","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":340,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765240/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","size":60402,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765240/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","placeholder_version":1,"placeholder":"6AcOBQCIh3x4aIf4iIo3aPxRwn9H","id":"1431710821267804240","height":512,"filename":"xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b_grid_0.webp","content_type":"image/webp","content_scan_version":2}],"application_id":"936929561302675456","progress_percent":87}},"seq":37,"ts":"18:27:40.003"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024182641690580089i-u12345-c1234567890987654321-bot:midjourney","verb":"blend","jobType":"image","status":"completed","created":"2025-10-24T18:26:41.706Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:26:37.641Z","blendUrls":["blob_0","blob_1"],"blendDimensions":"Portrait"},"updated":"2025-10-24T18:27:44.488Z","response":{"type":0,"tts":false,"timestamp":"2025-10-24T18:27:44.118000+00:00","pinned":false,"nonce":"14759609867849107127","mentions":[{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null}],"mention_roles":[],"mention_everyone":false,"id":"1431710839836250177","flags":0,"embeds":[],"edited_timestamp":null,"content":"**<https://s.mj.run/xxxxx-1jbng> <https://s.mj.run/xxxxxxxxT8V8> --ar 2:3 --v 7.0 --s 250** - <@9876543210123456789> (relaxed)","components":[{"type":1,"id":1,"components":[{"type":2,"style":2,"label":"U1","id":2,"custom_id":"MJ::JOB::upsample::1::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"U2","id":3,"custom_id":"MJ::JOB::upsample::2::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"U3","id":4,"custom_id":"MJ::JOB::upsample::3::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"U4","id":5,"custom_id":"MJ::JOB::upsample::4::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"id":6,"emoji":{"name":"🔄"},"custom_id":"MJ::JOB::reroll::0::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b::SOLO"}]},{"type":1,"id":7,"components":[{"type":2,"style":2,"label":"V1","id":8,"custom_id":"MJ::JOB::variation::1::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"V2","id":9,"custom_id":"MJ::JOB::variation::2::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"V3","id":10,"custom_id":"MJ::JOB::variation::3::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"type":2,"style":2,"label":"V4","id":11,"custom_id":"MJ::JOB::variation::4::xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b"},{"url":"https://www.midjourney.com/jobs/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b","type":2,"style":5,"label":"​","id":12}]}],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[{"width":1792,"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765936/matthieu_leblanc_975_None_xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b.png","size":5358165,"proxy_url":"https://media.discordapp.net/attachments/1234567890987654321/123456789098765936/matthieu_leblanc_975_None_xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b.png","placeholder_version":1,"placeholder":"6AcOBQCIh3x4aIf4iIo3aPxAsm9H","id":"1431710839530061936","height":2688,"filename":"matthieu_leblanc_975_None_xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b.png","content_type":"image/png","content_scan_version":2}],"buttons":["U1","U2","U3","U4","🔄","V1","V2","V3","V4"],"imageUx":[{"id":1,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b/0_0.jpeg"},{"id":2,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b/0_1.jpeg"},{"id":3,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b/0_2.jpeg"},{"id":4,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-8194e3f4fa1b/0_3.jpeg"}]},"code":200},"seq":39,"ts":"18:27:44.502"}
```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
# With URLs
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/blend" \
     -d '{"imageUrl_1":"https://example.com/1.jpg","imageUrl_2":"https://example.com/2.jpg","blendDimensions":"Square","stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/blend', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    imageUrl_1: 'https://example.com/1.jpg',
    imageUrl_2: 'https://example.com/2.jpg',
    blendDimensions: 'Square',
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/blend',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'imageUrl_1': 'https://example.com/1.jpg',
        'imageUrl_2': 'https://example.com/2.jpg',
        'blendDimensions': 'Square',
        'stream': False
    }
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  function clearInputImageBlob(index) {
    document.getElementById(`input-imageBlob_${index}`).value = '';
    return false;
  }

  async function apiExecuteJobsBlend() {
    let hasFile = false;

    for (let i = 1; i <= 5; i++) {
      const fileInput = document.getElementById(`input-imageBlob_${i}`).files[0];
      if (fileInput) {
        hasFile = true;
        break;
      }
    }

    if (hasFile) {
      const formData = new FormData();

      for (let i = 1; i <= 5; i++) {
        const fileInput = document.getElementById(`input-imageBlob_${i}`).files[0];
        if (fileInput) {
          formData.append(`imageBlob_${i}`, fileInput);
        }
      }

      await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/blend', 'input', formData);
    } else {
      await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/blend', 'input');
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageUrl_1"><span>imageUrl_1<small> (required - use URL or upload file below)</small></span>
        <input id="input-imageUrl_1" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob_1"><span>Upload image 1<small> (required - use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob(1)">✖️</button>
          <input id="input-imageBlob_1" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-imageUrl_2"><span>imageUrl_2<small> (required - use URL or upload file below)</small></span>
        <input id="input-imageUrl_2" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob_2"><span>Upload image 2<small> (required - use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob(2)">✖️</button>
          <input id="input-imageBlob_2" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-imageUrl_3"><span>imageUrl_3<small> (optional - use URL or upload file below)</small></span>
        <input id="input-imageUrl_3" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob_3"><span>Upload image 3<small> (optional - use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob(3)">✖️</button>
          <input id="input-imageBlob_3" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-imageUrl_4"><span>imageUrl_4<small> (optional - use URL or upload file below)</small></span>
        <input id="input-imageUrl_4" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob_4"><span>Upload image 4<small> (optional - use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob(4)">✖️</button>
          <input id="input-imageBlob_4" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-imageUrl_5"><span>imageUrl_5<small> (optional - use URL or upload file below)</small></span>
        <input id="input-imageUrl_5" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob_5"><span>Upload image 5<small> (optional - use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob(5)">✖️</button>
          <input id="input-imageBlob_5" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-blendDimensions"><span>blendDimensions<small> (optional - Square by default)</small></span>
        <select id="input-blendDimensions" class="input-element input-query-param">
          <option value="Square">Square</option>
          <option value="Portrait">Portrait</option>
          <option value="Landscape">Landscape</option>
        </select>
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming), default</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsBlend()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-button ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-button
## Execute Midjourney Buttons
<small>October 27, 2025 (February 19, 2026)</small>

---

Execute button actions on completed Midjourney jobs (upscale, variations, zoom, pan, reroll, etc.).

**Execute-Once Pattern:** U1-U4 upscale buttons can only be executed once per job. Subsequent requests return the existing child job immediately.
> **https://api.useapi.net/v3/midjourney/jobs/button**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "jobId": "j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney",
  "button": "U1",
  "stream": true,
  "replyUrl": "https://your-server.com/webhook",
  "replyRef": "your-reference-id"
}
```

### Parameters

- `jobId` is **required**. Parent job ID from completed imagine/button job.
  Must be a valid v3 job ID format.
  Parent job must have `status: "completed"`.

- `button` is **required**. Button label to execute from the parent job's `response.buttons` array.
  Only buttons available in completed parent job can be used.
  See [Supported Buttons](#supported-buttons) below.

- `mask` is **optional**. Required only for `Vary (Region)` button, must be base64-encoded **WebP** format.
  See [Vary Region Mask Editor](/docs/api-midjourney-v3/vary-region-mask-editor) for details.

- `prompt` is **optional**. Required for `Custom Zoom` button.
  When [Remix mode](/docs/api-midjourney-v3/post-midjourney-jobs-remix) is active, variation buttons (`V1`, `V2`, `V3`, `V4`, `Vary (Region)`, `Vary (Strong)`, `Vary (Subtle)`), pan buttons (`⬅️`, `➡️`, `⬆️`, `⬇️`), and `🔄` (Reroll) also accept a prompt. If not provided, the original prompt will be used.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

**Note:** Button job executes in the same channel as the parent job.

### Supported Buttons

**Upscale (Execute-Once):**
- `U1`, `U2`, `U3`, `U4` - Upscale one of four grid images
- **Note:** Can only be executed once per parent job. Subsequent requests return existing child job.

**Variations:**
- `V1`, `V2`, `V3`, `V4` - Create variations of one of four grid images
- `Make Variations` - Create variations
- `Vary (Strong)` - Strong variation
- `Vary (Subtle)` - Subtle variation
- `Vary (Region)` - Regional variation (requires `mask` parameter)

**Zoom:**
- `Zoom Out 1.5x` - Zoom out 1.5x
- `Zoom Out 2x` - Zoom out 2x
- `Custom Zoom` - Custom zoom (prompts for parameters)

**Pan:**
- `⬅️`, `➡️`, `⬆️`, `⬇️` - Pan in direction

**Upscale Quality:**
- `Upscale (2x)`, `Upscale (4x)` - Upscale resolution
- `Upscale (Subtle)`, `Upscale (Creative)` - Upscale variants
- `Redo Upscale (2x)`, `Redo Upscale (4x)` - Redo upscale
- `Redo Upscale (Subtle)`, `Redo Upscale (Creative)` - Redo upscale variants

**Video:**
- `Animate (Low motion)`, `Animate (High motion)` - Animate image
- `Extend (Low motion)`, `Extend (High motion)` - Extend video

**Other:**
- `🔄` - Reroll (regenerate with same prompt)
- `Make Square` - Make image square
- `Remaster` - Remaster image

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**200**
**200 OK**

Execute-once button (U1-U4) already executed - returning existing child job.

**Note:** U1-U4 buttons return existing child job on subsequent executions (no 409 error).

**201**
**201 Created**

New button job created.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

```json
{
    "jobid": "j1024182422328516474i-u12345-c1234567890987654321-bot:midjourney",
    "verb": "button",
    "jobType": "image",
    "status": "created",
    "created": "2025-10-24T18:24:22.340Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:24:21.243Z",
        "stream": false,
        "button": "U1",
        "jobId": "j1024181441023299840i-u12345-c1234567890987654321-bot:midjourney"
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "jobId is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**404**
**404 Not Found**

```json
{
  "error": "Parent job not found"
}
```

**410**
**410 Gone**

Parent job is older than 62 days.

```json
{
  "error": "Parent job has expired"
}
```

**429**
**429 Too Many Requests**

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024182444310873122i-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:24:44.373"}

data: {"event":"midjourney_created","job":{"jobid":"j1024182444310873122i-u12345-c1234567890987654321-bot:midjourney","verb":"button","jobType":"image","status":"created","created":"2025-10-24T18:24:44.325Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:24:43.248Z","button":"U2","jobId":"j1024181441023299840i-u12345-c1234567890987654321-bot:midjourney"},"updated":"2025-10-24T18:24:45.449Z"},"seq":12,"ts":"18:24:45.474"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182444310873122i-u12345-c1234567890987654321-bot:midjourney","verb":"button","jobType":"image","status":"progress","created":"2025-10-24T18:24:44.325Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:24:43.248Z","button":"U2","jobId":"j1024181441023299840i-u12345-c1234567890987654321-bot:midjourney"},"updated":"2025-10-24T18:24:46.039Z","response":{"content":"Upscaling image #2 with **cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (Waiting to start)"}},"seq":14,"ts":"18:24:46.050"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024182444310873122i-u12345-c1234567890987654321-bot:midjourney","verb":"button","jobType":"image","status":"completed","created":"2025-10-24T18:24:44.325Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:24:43.248Z","button":"U2","jobId":"j1024181441023299840i-u12345-c1234567890987654321-bot:midjourney"},"updated":"2025-10-24T18:24:47.155Z","response":{"content":"**cat in the hat --v 7.0 --s 250** - Image #2 <@9876543210123456789>","attachments":[{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765027/matthieu_leblanc_975_cat_in_the_hat_xxxxxxxx-xxxx-xxxx-xxxx-e994e697adb0.png","width":1024,"height":1024}],"buttons":["Upscale (Subtle)","Upscale (Creative)","Vary (Subtle)","Vary (Strong)","Vary (Region)","Zoom Out 2x","Zoom Out 1.5x","Custom Zoom","⬅️","➡️","⬆️","⬇️","Animate (High motion)","Animate (Low motion)"]},"code":200},"seq":17,"ts":"18:24:47.170"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/button" \
     -d '{"jobId":"j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney","button":"U1","stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/button', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobId: 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
    button: 'U1',
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/button',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'jobId': 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
        'button': 'U1',
        'stream': False
    }
)

result = response.json()
print('Job created:', result['jobid'])

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsButton() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/button', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token</span>
        <input id="input-token" type="text" class="input-element" required>
      </label>
      <label for="input-jobId"><span>jobId<small> (required - parent job)</small></span>
        <input id="input-jobId" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-button"><span>button<small> (required)</small></span>
        <select id="input-button" class="input-element input-query-param">
          <option></option>
          <option>U1</option>
          <option>U2</option>
          <option>U3</option>
          <option>U4</option>
          <option>V1</option>
          <option>V2</option>
          <option>V3</option>
          <option>V4</option>
          <option>⬅️</option>
          <option>➡️</option>
          <option>⬆️</option>
          <option>⬇️</option>
          <option>🔄</option>
          <option>Vary (Region)</option>
          <option>Vary (Strong)</option>
          <option>Vary (Subtle)</option>
          <option>Zoom Out 1.5x</option>
          <option>Zoom Out 2x</option>
          <option>Upscale (2x)</option>
          <option>Upscale (4x)</option>
          <option>Upscale (Subtle)</option>
          <option>Upscale (Creative)</option>
          <option>Redo Upscale (2x)</option>
          <option>Redo Upscale (4x)</option>
          <option>Redo Upscale (Subtle)</option>
          <option>Redo Upscale (Creative)</option>
          <option>Make Square</option>
          <option>Make Variations</option>
          <option>Remaster</option>
          <option>Custom Zoom</option>
          <option>Animate (Low motion)</option>
          <option>Animate (High motion)</option>
          <option>Extend (Low motion)</option>
          <option>Extend (High motion)</option>
        </select>
      </label>
      <label for="input-mask"><span>mask<small> (optional - required for Vary (Region), see <a href="/docs/api-midjourney-v3/vary-region-mask-editor">Mask Editor</a>)</small></span>
        <input id="input-mask" type="text" class="input-element input-query-param">
      </label>
      <label for="input-prompt"><span>prompt<small> (optional - required for Custom Zoom, usable in Remix mode)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming), default</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsButton()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-describe ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-describe
## Midjourney /describe Command
<small>October 27, 2025 (January 5, 2026)</small>

---

Generate text prompts from an image using Midjourney's [/describe](https://docs.midjourney.com/docs/explore-prompting) command. Returns 4 prompt suggestions. 
> **https://api.useapi.net/v3/midjourney/jobs/describe**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "imageUrl": "https://example.com/image.jpg",
  "stream": true,
  "replyUrl": "https://your-server.com/webhook"
}
```

### Parameters

- `channel` is optional. Discord channel ID to use. See [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) for configured channels.
  If not provided, API automatically selects available channel with capacity.
  Specify when you want to use a specific configured channel.

- `imageUrl` **OR** `imageBlob` is **required** (mutually exclusive).
  - `imageUrl` - URL to image. Maximum file size: 10 MB.
  - `imageBlob` - Image file upload, use `Content-Type: multipart/form-data`. Maximum file size: 10 MB.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

```json
{
    "jobid": "j1024182321776001078-u12345-c1234567890987654321-bot:midjourney",
    "verb": "describe",
    "status": "created",
    "created": "2025-10-24T18:23:21.776Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:23:19.669Z",
        "stream": false,
        "describeUrl": "blob"
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "Either imageUrl or imageBlob is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024182234526029456-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:22:35.843"}

data: {"event":"midjourney_created","job":{"jobid":"j1024182234526029456-u12345-c1234567890987654321-bot:midjourney","verb":"describe","status":"created","created":"2025-10-24T18:22:34.526Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:22:31.696Z","describeUrl":"blob"},"updated":"2025-10-24T18:22:37.785Z"},"seq":12,"ts":"18:22:37.805"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024182234526029456-u12345-c1234567890987654321-bot:midjourney","verb":"describe","status":"progress","created":"2025-10-24T18:22:34.526Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:22:31.696Z","describeUrl":"blob"},"updated":"2025-10-24T18:22:38.704Z","response":{"content":"","components":[]}},"seq":14,"ts":"18:22:38.715"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024182234526029456-u12345-c1234567890987654321-bot:midjourney","verb":"describe","status":"completed","created":"2025-10-24T18:22:34.526Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:22:31.696Z","describeUrl":"blob"},"updated":"2025-10-24T18:22:42.510Z","response":{"embeds":[{"description":"1️⃣ a vintage bmw motorcycle from the early showa era, with an engine visible through its side panels and two wheels on a white background. the bike is black in color, showcasing classic japanese design elements such as chrome accents and leather seats. it's positioned at eye level to highlight details like brand logos and steel frame construction. --ar 16:9\n\n2️⃣ a vintage bmw motorcycle from the early 1920s, displayed on a white background, showcasing its classic design and powerful engine. the image was created using focus stacking, a photographic technique that combines multiple images taken at different focus distances to achieve a greater depth of field. the photograph was taken with provia, a type of color reversal film known for its vivid and accurate color reproduction. --ar 16:9\n\n3️⃣ a vintage bmw motorcycle from the early 20th century, black with silver accents and a leather seat, displayed on a white background, high resolution, captured with a canon eos camera, studio lighting, product photography, minimalistic style, focusing on the intricate details of the engine and frame, side view, perspective angle. --ar 16:9\n\n4️⃣ a vintage bmw motorcycle with an engine, a black body, and chrome details on the side stands against a white background. the bike is centered in the frame, showcasing its classic design with two front wheels and one rear wheel. it has a leather seat, steel handlebar levers, and visible details from right to left, in the style of bmw. --ar 16:9"}],"content":"1️⃣ a vintage bmw motorcycle from the early showa era...[abbreviated for brevity]","components":[{"components":[{"custom_id":"MJ::Job::PicReader::1"},{"custom_id":"MJ::Job::PicReader::2"},{"custom_id":"MJ::Job::PicReader::3"},{"custom_id":"MJ::Job::PicReader::4"},{"custom_id":"MJ::Picread::Retry"}]},{"components":[{"custom_id":"MJ::Job::PicReader::all"}]}]},"code":200},"seq":17,"ts":"18:22:42.524"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
# With URL
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/describe" \
     -d '{"imageUrl":"https://example.com/image.jpg","stream":false}'

# With file upload
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "imageBlob=@image.jpg" \
     -F "stream=false" \
     "https://api.useapi.net/v3/midjourney/jobs/describe"
```

**JavaScript**
``` javascript
// With URL
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/describe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    imageUrl: 'https://example.com/image.jpg',
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

# With URL
response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/describe',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'imageUrl': 'https://example.com/image.jpg',
        'stream': False
    }
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  function clearInputImageBlob() {
    document.getElementById('input-imageBlob').value = '';
    return false;
  }

  async function apiExecuteJobsDescribe() {
    const imageFile = document.getElementById('input-imageBlob').files[0];

    if (imageFile) {
      const formData = new FormData();
      formData.append('imageBlob', imageFile);

      await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/describe', 'input', formData);
    } else {
      await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/describe', 'input');
    }
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageUrl"><span>imageUrl<small> (use URL or upload file below)</small></span>
        <input id="input-imageUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-imageBlob"><span>Upload image file<small> (use file or URL above)</small></span>
        <div style="display:flex">
          <button type="button" onclick="clearInputImageBlob()">✖️</button>
          <input id="input-imageBlob" type="file" class="input-element" accept="image/*">
        </div>
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming), default</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsDescribe()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-fast ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-fast
## Switch to Fast Mode
<small>October 27, 2025 (January 5, 2026)</small>

---

Switch Midjourney account to [Fast mode](https://docs.midjourney.com/docs/fast-mode) using the /fast command.
> **https://api.useapi.net/v3/midjourney/jobs/fast**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Mode setting will be available in `response.settings.fast` when job completes.

```json
{
    "jobid": "j1024181945741973836-u12345-c1234567890987654321-bot:midjourney",
    "verb": "fast",
    "status": "created",
    "created": "2025-10-24T18:19:45.741Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:19:44.656Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181957527528075-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:19:57.544"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181957527528075-u12345-c1234567890987654321-bot:midjourney","verb":"fast","status":"created","created":"2025-10-24T18:19:57.527Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:56.466Z"},"updated":"2025-10-24T18:19:59.396Z"},"seq":11,"ts":"18:19:59.409"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181957527528075-u12345-c1234567890987654321-bot:midjourney","verb":"fast","status":"progress","created":"2025-10-24T18:19:57.527Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:56.466Z"},"updated":"2025-10-24T18:19:59.541Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:59.472000+00:00","position":0,"pinned":false,"nonce":"1025181957527528075","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"fast","id":"1431708889895669880","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"fast","id":"1431708889895669880"},"id":"1431708890969542676","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":15,"ts":"18:19:59.562"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181957527528075-u12345-c1234567890987654321-bot:midjourney","verb":"fast","status":"completed","created":"2025-10-24T18:19:57.527Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:56.466Z"},"updated":"2025-10-24T18:20:00.078Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:59.472000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"fast","id":"1431708889895669880","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"fast","id":"1431708889895669880"},"id":"1431708890969542676","flags":64,"embeds":[],"edited_timestamp":null,"content":"Done! Note that once you exhaust your fast hours, you can purchase more on the website: <https://midjourney.com/account>. To conserve your fast hours, use `/relax` to switch back to relax mode.","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"relax":false,"fast":true,"turbo":false}},"code":200},"seq":17,"ts":"18:20:00.096"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Speed mode settings will be available in `response.settings` when job completes:

```typescript
settings?: {
  relax?: boolean             // Relax mode
  fast?: boolean              // Fast mode
  turbo?: boolean             // Turbo mode
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/fast" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/fast', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/fast',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsFast() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/fast', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsFast()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-imagine ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-imagine
## Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command
<small>October 27, 2025 (January 5, 2026)</small>

---

Generate images or videos from text prompts using Midjourney's [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command.

We provide full support for **video generation**, including all video-specific parameters such as `--video`, `--motion low`, `--motion high`, `--raw`, `--loop`, and `--end`. See [official documentation](https://docs.midjourney.com/hc/en-us/articles/37460773864589-Video) for details.

Your current [Midjourney Settings and Presets](https://docs.midjourney.com/docs/settings-and-presets) will be used.
> **https://api.useapi.net/v3/midjourney/jobs/imagine**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

### Request Body
```json
{
  "prompt": "a cat in a hat --ar 16:9",
  "stream": true,
  "channel": "1234567890123456789",
  "replyUrl": "https://your-server.com/webhook",
  "replyRef": "your-reference-id"
}
```

### Parameters

- `channel` is optional. Discord channel ID to use. See [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) for configured channels.
  If not provided, API automatically selects available channel with capacity.
  Specify when you want to use a specific configured channel.

- `prompt` is **required**. Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) prompt.
  Maximum length 5000 characters.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)  

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

```json
{
    "jobid": "j1024181105489769750i-u12345-c1234567890987654321-bot:midjourney",
    "verb": "imagine",
    "jobType": "image",
    "status": "created",
    "created": "2025-10-24T18:11:05.501Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:11:04.335Z",
        "stream": false,
        "prompt": "cat in the hat"
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**429**
**429 Too Many Requests**

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:11:25.857"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"created","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:26.898Z"},"seq":12,"ts":"18:11:26.919"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"progress","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:32.286Z","response":{"webhook_id":"936929561302675456","type":20,"content":"**cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (0%) (turbo)","progress_percent":0}},"seq":17,"ts":"18:11:32.297"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"progress","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:35.462Z","response":{"webhook_id":"936929561302675456","type":20,"content":"**cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (15%) (turbo)","progress_percent":15}},"seq":24,"ts":"18:11:35.556"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"progress","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:36.172Z","response":{"webhook_id":"936929561302675456","type":20,"content":"**cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (38%) (turbo)","attachments":[{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765172/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d_grid_0.webp","width":512,"height":512}],"progress_percent":38}},"seq":26,"ts":"18:11:36.190"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"progress","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:39.699Z","response":{"webhook_id":"936929561302675456","type":20,"content":"**cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (96%) (turbo)","attachments":[{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765842/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d_grid_0.webp","width":512,"height":512}],"progress_percent":96}},"seq":32,"ts":"18:11:39.724"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney","verb":"imagine","jobType":"image","status":"completed","created":"2025-10-24T18:11:25.829Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:11:24.573Z","prompt":"cat in the hat"},"updated":"2025-10-24T18:11:42.798Z","response":{"type":0,"content":"**cat in the hat --v 7.0 --s 250** - <@9876543210123456789> (turbo)","components":[{"type":1,"components":[{"type":2,"style":2,"label":"U1","custom_id":"MJ::JOB::upsample::1::xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d"},{"type":2,"style":2,"label":"U2","custom_id":"MJ::JOB::upsample::2::xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d"}]}],"attachments":[{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765624/matthieu_leblanc_975_cat_in_the_hat_xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d.png","width":2048,"height":2048}],"buttons":["U1","U2","U3","U4","🔄","V1","V2","V3","V4"],"imageUx":[{"id":1,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d/0_0.jpeg"},{"id":2,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d/0_1.jpeg"},{"id":3,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d/0_2.jpeg"},{"id":4,"url":"https://cdn.midjourney.com/xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d/0_3.jpeg"}]},"code":200},"seq":34,"ts":"18:11:42.818"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/imagine" \
     -d '{"prompt":"a cat in a hat","stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/imagine', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'a cat in a hat',
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/imagine',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'prompt': 'a cat in a hat',
        'stream': False
    }
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsImagine() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/imagine', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-prompt"><span>prompt</span>
        <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-stream"><span>stream</span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming), default</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional webhook)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional reference)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsImagine()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-info ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-info
## Get Midjourney Account Info
<small>October 27, 2025 (January 5, 2026)</small>

---

Get Midjourney account information using the [/info](https://docs.midjourney.com/docs/info) command. Returns subscription details, fast time remaining, job mode, and current settings.
> **https://api.useapi.net/v3/midjourney/jobs/info**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.  
  Returned in all responses and callbacks as `response.replyRef`.  
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Account settings will be available in `response.settings` when job completes.

```json
{
    "jobid": "j1024181848571921040-u12345-c1234567890987654321-bot:midjourney",
    "verb": "info",
    "status": "created",
    "created": "2025-10-24T18:18:48.571Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:18:47.224Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "channel parameter is required when multiple channels (3) are configured"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:19:09.469"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"info","status":"created","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:10.420Z"},"seq":12,"ts":"18:19:10.443"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"info","status":"progress","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:10.976Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:10.865000+00:00","position":0,"pinned":false,"nonce":"1025181909456319196","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"info","id":"1431708684915839209","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"info","id":"1431708684915839209"},"id":"1431708687097008169","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":14,"ts":"18:19:10.989"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"info","status":"completed","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:11.339Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:10.865000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"info","id":"1431708684915839209","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"info","id":"1431708684915839209"},"id":"1431708687097008169","flags":64,"embeds":[{"type":"rich","title":"Your info - matthieu_leblanc_975","id":"1431708688757817458","description":"**User ID**:                    xxxxxxxx-xxxx-xxxx-xxxx-399f36ef42de\n**Subscription**:               Standard (Active yearly, renews next on <t:1788573715>)\n**Job Mode**:                   Relaxed\n**Visibility Mode**:            Public\n**Fast Time Remaining**:        9.34/15.0 hours (62.27%)\n**Ranking Count**:              200\n**Lifetime Usage**:             970 images\n**Fast Usage**:                 609 images\n**Turbo Usage**:                23 images\n**Relaxed Usage**:              338 images\n\n**Queued Jobs (fast)**:                           0\n**Queued Jobs (relax)**:                          0\n**Running Jobs**:      None","content_scan_version":0,"color":0}],"edited_timestamp":null,"content":"**User ID**:                    xxxxxxxx-xxxx-xxxx-xxxx-399f36ef42de\n**Subscription**:               Standard (Active yearly, renews next on <t:1788573715>)\n**Job Mode**:                   Relaxed\n**Visibility Mode**:            Public\n**Fast Time Remaining**:        9.34/15.0 hours (62.27%)\n**Ranking Count**:              200\n**Lifetime Usage**:             970 images\n**Fast Usage**:                 609 images\n**Turbo Usage**:                23 images\n**Relaxed Usage**:              338 images\n\n**Queued Jobs (fast)**:                           0\n**Queued Jobs (relax)**:                          0\n**Running Jobs**:      None","components":[{"type":1,"id":1,"components":[{"url":"https://www.midjourney.com/imagine","type":2,"style":5,"label":"Go to your feed","id":2}]}],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"relax":true,"fast":false,"turbo":false}},"code":200},"seq":17,"ts":"18:19:11.354"}
```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Speed mode settings will be available in `response.settings` when job completes:

```typescript
settings?: {
  relax?: boolean             // Relax mode
  fast?: boolean              // Fast mode
  turbo?: boolean             // Turbo mode
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/info" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/info', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);
console.log('Account mode:', result.response.settings);
// { relax: false, fast: true, turbo: false }

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/info',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])
print('Account mode:', result['response']['settings'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsInfo() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/info', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsInfo()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-relax ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-relax
## Switch to Relax Mode
<small>October 27, 2025 (January 5, 2026)</small>

---

Switch Midjourney account to [Relax mode](https://docs.midjourney.com/docs/relax-mode) using the /relax command.
> **https://api.useapi.net/v3/midjourney/jobs/relax**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Mode setting will be available in `response.settings.relax` when job completes.

```json
{
    "jobid": "j1024181730288780346-u12345-c1234567890987654321-bot:midjourney",
    "verb": "relax",
    "status": "created",
    "created": "2025-10-24T18:17:30.288Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:17:29.230Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181745044609922-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:17:45.057"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181745044609922-u12345-c1234567890987654321-bot:midjourney","verb":"relax","status":"created","created":"2025-10-24T18:17:45.044Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:17:44.027Z"},"updated":"2025-10-24T18:17:46.175Z"},"seq":12,"ts":"18:17:46.185"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181745044609922-u12345-c1234567890987654321-bot:midjourney","verb":"relax","status":"progress","created":"2025-10-24T18:17:45.044Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:17:44.027Z"},"updated":"2025-10-24T18:17:46.445Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:17:46.251000+00:00","position":0,"pinned":false,"nonce":"1025181745044609922","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"relax","id":"1431708331008987248","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"relax","id":"1431708331008987248"},"id":"1431708332200165436","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":14,"ts":"18:17:46.467"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181745044609922-u12345-c1234567890987654321-bot:midjourney","verb":"relax","status":"completed","created":"2025-10-24T18:17:45.044Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:17:44.027Z"},"updated":"2025-10-24T18:17:46.944Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:17:46.251000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"relax","id":"1431708331008987248","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"relax","id":"1431708331008987248"},"id":"1431708332200165436","flags":64,"embeds":[],"edited_timestamp":null,"content":"Done! Your jobs now do not consume fast-hours, but might take a little longer. You can always switch back with `/fast`","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"relax":true,"fast":false,"turbo":false}},"code":200},"seq":17,"ts":"18:17:46.955"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Speed mode settings will be available in `response.settings` when job completes:

```typescript
settings?: {
  relax?: boolean             // Relax mode
  fast?: boolean              // Fast mode
  turbo?: boolean             // Turbo mode
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/relax" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/relax', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/relax',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsRelax() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/relax', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsRelax()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-remix ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-remix
## Toggle Remix Mode
<small>October 27, 2025 (January 5, 2026)</small>

---

Toggle Midjourney [Remix mode](https://docs.midjourney.com/docs/remix) using the /settings command. Remix mode allows you to change prompts and parameters when creating variations.
> **https://api.useapi.net/v3/midjourney/jobs/remix**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.  
  Returned in all responses and callbacks as `response.replyRef`.  
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Remix mode setting will be available in `response.settings.remix` when job completes.

```json
{
    "jobid": "j1024181607209142270-u12345-c1234567890987654321-bot:midjourney",
    "verb": "remix",
    "status": "created",
    "created": "2025-10-24T18:16:07.209Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:16:06.162Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181618938667002-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:16:18.953"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181618938667002-u12345-c1234567890987654321-bot:midjourney","verb":"remix","status":"created","created":"2025-10-24T18:16:18.938Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:16:17.931Z"},"updated":"2025-10-24T18:16:19.992Z"},"seq":11,"ts":"18:16:20.003"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181618938667002-u12345-c1234567890987654321-bot:midjourney","verb":"remix","status":"progress","created":"2025-10-24T18:16:18.938Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:16:17.931Z"},"updated":"2025-10-24T18:16:20.131Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:16:20.054000+00:00","position":0,"pinned":false,"nonce":"1025181618938667002","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer remix","id":"1431707970152169662","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer remix","id":"1431707970152169662"},"id":"1431707970663616715","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":15,"ts":"18:16:20.151"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181618938667002-u12345-c1234567890987654321-bot:midjourney","verb":"remix","status":"completed","created":"2025-10-24T18:16:18.938Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:16:17.931Z"},"updated":"2025-10-24T18:16:20.298Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:16:20.054000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer remix","id":"1431707970152169662","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer remix","id":"1431707970152169662"},"id":"1431707970663616715","flags":64,"embeds":[],"edited_timestamp":null,"content":"Remix mode turned on! Clicking the variation buttons will now give you a chance to edit your prompt! You can always turn this off by running `/prefer remix` again.","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"remix":true}},"code":200},"seq":17,"ts":"18:16:20.314"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Remix mode setting will be available in `response.settings` when job completes:

```typescript
settings?: {
  remix?: boolean             // Remix mode
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/remix" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/remix', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/remix',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsRemix() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/remix', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsRemix()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-seed ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-seed
## Get Midjourney Seed
<small>October 27, 2025 (January 5, 2026)</small>

---

Retrieve the [seed](https://docs.midjourney.com/docs/seeds) and **four separate upscaled** images for the following completed jobs: 
* [jobs/imagine](/docs/api-midjourney-v3/post-midjourney-jobs-imagine)
* [jobs/button](/docs/api-midjourney-v3/post-midjourney-jobs-button)
* [jobs/blend](/docs/api-midjourney-v3/post-midjourney-jobs-blend)

Please note that video generation jobs are not supported.
> **https://api.useapi.net/v3/midjourney/jobs/seed**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "jobId": "j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney"
}
```

### Parameters

- `jobId` is **required**. Parent job ID from completed image job.
  Job must have:
  - `status: "completed"`
  - `jobType: "image"` (not video)
  - Message ID present

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

```json
{
    "jobid": "j1024181534748808540-u12345-c1234567890987654321-bot:midjourney",
    "verb": "seed",
    "status": "created",
    "created": "2025-10-24T18:15:34.748Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:15:33.608Z",
        "stream": false,
        "jobId": "j1024181441023299840i-u12345-c1234567890987654321-bot:midjourney"
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "Parent job status is \"progress\", must be \"completed\" to get seed"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**404**
**404 Not Found**

```json
{
  "error": "Parent job not found"
}
```

**410**
**410 Gone**

Parent job expired (older than 62 days).

```json
{
  "error": "Parent job has expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181334913815452-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:13:34.977"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181334913815452-u12345-c1234567890987654321-bot:midjourney","verb":"seed","status":"completed","created":"2025-10-24T18:13:34.913Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:13:33.684Z","jobId":"j1024181125701303160i-u12345-c1234567890987654321-bot:midjourney"},"response":{"content":"**cat in the hat --v 7.0 --s 250**\n**Job ID**: xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d\n**seed** 3937070146","attachments":[{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765124/anonymous_cat_in_the_hat_0_xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d.png","width":1024,"height":1024},{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765936/anonymous_cat_in_the_hat_1_xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d.png","width":1024,"height":1024},{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765279/anonymous_cat_in_the_hat_2_xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d.png","width":1024,"height":1024},{"url":"https://cdn.discordapp.com/attachments/1234567890987654321/123456789098765203/anonymous_cat_in_the_hat_3_xxxxxxxx-xxxx-xxxx-xxxx-bbd798ffcb5d.png","width":1024,"height":1024}]},"code":200,"updated":"2025-10-24T18:13:38.213Z"},"seq":16,"ts":"18:13:38.226"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/seed" \
     -d '{"jobId":"j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney","stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/seed', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobId: 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
    stream: false
  })
});

const result = await response.json();
console.log('Seed:', result.response.seed);

// Use seed in next imagine prompt
const nextJob = await fetch('https://api.useapi.net/v3/midjourney/jobs/imagine', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: `a cat in a hat --seed ${result.response.seed}`,
    stream: false
  })
});
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/seed',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'jobId': 'j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney',
        'stream': False
    }
)

result = response.json()
seed = result['response']['seed']
print(f'Seed: {seed}')

# Use seed in next imagine prompt
next_job = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/imagine',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'prompt': f'a cat in a hat --seed {seed}',
        'stream': False
    }
)
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsSeed() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/seed', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-jobId"><span>jobId<small> (required - parent job ID)</small></span>
        <input id="input-jobId" type="text" class="input-element input-query-param" required aria-required="true">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsSeed()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-settings ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-settings
## Midjourney Settings
<small>October 27, 2025 (January 5, 2026)</small>

---

Open the Midjourney settings panel using the [/settings](https://docs.midjourney.com/docs/settings-and-presets) command. Returns current settings including model version, stylization, RAW mode, personalization, privacy mode, remix mode, variation mode, speed modes, and the current suffix applied to prompts.
> **https://api.useapi.net/v3/midjourney/jobs/settings**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Current settings will be available in `response.settings` when job completes.

```json
{
    "jobid": "j1024181848571921040-u12345-c1234567890987654321-bot:midjourney",
    "verb": "settings",
    "status": "created",
    "created": "2025-10-24T18:18:48.571Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T18:18:47.224Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "channel parameter is required when multiple channels (3) are configured"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"18:19:09.469"}

data: {"event":"midjourney_created","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"settings","status":"created","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:10.420Z"},"seq":12,"ts":"18:19:10.443"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"settings","status":"progress","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:10.976Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:10.865000+00:00","position":0,"pinned":false,"nonce":"1025181909456319196","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"settings","id":"1431708684915839209","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"settings","id":"1431708684915839209"},"id":"1431708687097008169","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":14,"ts":"18:19:10.989"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024181909456319196-u12345-c1234567890987654321-bot:midjourney","verb":"settings","status":"completed","created":"2025-10-24T18:19:09.456Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T18:19:08.457Z"},"updated":"2025-10-24T18:19:11.339Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T18:19:10.865000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"settings","id":"1431708684915839209","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"settings","id":"1431708684915839209"},"id":"1431708687097008169","flags":64,"embeds":[],"edited_timestamp":null,"content":"Adjust your settings here. Current suffix: ` --v 7 --s 250`","components":[{"type":1,"id":1,"components":[{"type":3,"placeholder":"Select a version","options":[{"value":"default","label":"Use the default model (V7)","description":"(default)"},{"value":"7","label":"Midjourney Model V7","emoji":{"name":"7️⃣"},"default":true},{"value":"6.1","label":"Midjourney Model V6.1","emoji":{"name":"6️⃣"}},{"value":"6","label":"Midjourney Model V6.0","emoji":{"name":"6️⃣"}},{"value":"niji 6","label":"Niji Model V6","emoji":{"name":"🌈"}},{"value":"5.2","label":"Midjourney Model V5.2","emoji":{"name":"5️⃣"}},{"value":"5.1","label":"Midjourney Model V5.1","emoji":{"name":"5️⃣"}},{"value":"niji 5","label":"Niji Model V5","emoji":{"name":"🍎"}},{"value":"5","label":"Midjourney Model V5.0","emoji":{"name":"5️⃣"}},{"value":"niji 4","label":"Niji Model V4","emoji":{"name":"🌈"}},{"value":"4","label":"Midjourney Model V4","emoji":{"name":"4️⃣"}},{"value":"3","label":"Midjourney Model V3","emoji":{"name":"3️⃣"}},{"value":"2","label":"Midjourney Model V2","emoji":{"name":"2️⃣"}},{"value":"1","label":"Midjourney Model V1","emoji":{"name":"1️⃣"}}],"min_values":1,"max_values":1,"id":2,"custom_id":"MJ::Settings::VersionSelector"}]},{"type":1,"id":3,"components":[{"type":2,"style":2,"label":"RAW Mode","id":4,"emoji":{"name":"🔧"},"custom_id":"MJ::Settings::Style::raw"},{"type":2,"style":2,"label":"Stylize low","id":5,"emoji":{"name":"🖌️"},"custom_id":"MJ::Settings::Stylization::50"},{"type":2,"style":2,"label":"Stylize med","id":6,"emoji":{"name":"🖌️"},"custom_id":"MJ::Settings::Stylization::100"},{"type":2,"style":3,"label":"Stylize high","id":7,"emoji":{"name":"🖌️"},"custom_id":"MJ::Settings::Stylization::250"},{"type":2,"style":2,"label":"Stylize very high","id":8,"emoji":{"name":"🖌️"},"custom_id":"MJ::Settings::Stylization::750"}]},{"type":1,"id":9,"components":[{"type":2,"style":2,"label":"Personalization","id":10,"emoji":{"name":"🙋"},"custom_id":"MJ::Settings::PersonalizedStyle"},{"type":2,"style":3,"label":"Public mode","id":11,"emoji":{"name":"🧍"},"custom_id":"MJ::Settings::PrivateMode::off"},{"type":2,"style":3,"label":"Remix mode","id":12,"emoji":{"name":"🎛️"},"custom_id":"MJ::Settings::RemixMode"},{"type":2,"style":3,"label":"Strong Variation Mode","id":13,"emoji":{"name":"🎨"},"custom_id":"MJ::Settings::HighVariabilityMode::1"},{"type":2,"style":2,"label":"Subtle Variation Mode","id":14,"emoji":{"name":"🎨"},"custom_id":"MJ::Settings::HighVariabilityMode::0"}]},{"type":1,"id":15,"components":[{"type":2,"style":2,"label":"Turbo mode","id":16,"emoji":{"name":"⚡"},"custom_id":"MJ::Settings::TurboMode"},{"type":2,"style":2,"label":"Fast mode","id":17,"emoji":{"name":"🐇"},"custom_id":"MJ::Settings::FastMode"},{"type":2,"style":3,"label":"Relax mode","id":18,"emoji":{"name":"🐢"},"custom_id":"MJ::Settings::RelaxMode"},{"type":2,"style":2,"label":"Reset Settings","id":19,"custom_id":"MJ::Settings::ResetSettings"}]}],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"version":"7","raw":false,"stylize":250,"personalization":false,"public":true,"remix":true,"variability":true,"turbo":false,"fast":false,"relax":true,"suffix":"--v 7 --s 250"}},"code":200},"seq":17,"ts":"18:19:11.354"}
```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Current settings will be available in `response.settings` when job completes:

```typescript
settings?: {
  version?: string            // Model version: "7", "6.1", "niji 6", "default"
  raw?: boolean               // RAW mode
  stylize?: number            // Stylization value: 50, 100, 250, 750
  personalization?: boolean   // Personalization mode
  public?: boolean            // Public mode (true) or Private mode (false)
  remix?: boolean             // Remix mode
  variability?: boolean       // Variation mode: true = High/Strong, false = Low/Subtle
  turbo?: boolean             // Turbo mode
  fast?: boolean              // Fast mode
  relax?: boolean             // Relax mode
  suffix?: string             // Current suffix applied to prompts (e.g., "--v 7 --s 250")
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/settings" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/settings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);
console.log('Settings:', result.response.settings);
// { version: "7", raw: false, stylize: 250, personalization: false, public: true, remix: true, variability: true, turbo: false, fast: false, relax: true, suffix: "--v 7 --s 250" }

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/settings',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])
print('Settings:', result['response']['settings'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsSettings() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/settings', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsSettings()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-turbo ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-turbo
## Switch to Turbo Mode
<small>October 27, 2025 (January 5, 2026)</small>

---

Switch Midjourney account to Turbo mode using the /turbo command.
> **https://api.useapi.net/v3/midjourney/jobs/turbo**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.
  Returned in all responses and callbacks as `response.replyRef`.
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Mode setting will be available in `response.settings.turbo` when job completes.

```json
{
    "jobid": "j1024172410167793966-u12345-c1234567890987654321-bot:midjourney",
    "verb": "turbo",
    "status": "created",
    "created": "2025-10-24T17:24:10.167Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T17:24:09.116Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024172426467483135-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"17:24:26.481"}

data: {"event":"midjourney_created","job":{"jobid":"j1024172426467483135-u12345-c1234567890987654321-bot:midjourney","verb":"turbo","status":"created","created":"2025-10-24T17:24:26.467Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:24:25.528Z"},"updated":"2025-10-24T17:24:27.576Z"},"seq":11,"ts":"17:24:27.591"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024172426467483135-u12345-c1234567890987654321-bot:midjourney","verb":"turbo","status":"progress","created":"2025-10-24T17:24:26.467Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:24:25.528Z"},"updated":"2025-10-24T17:24:27.725Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T17:24:27.643000+00:00","position":0,"pinned":false,"nonce":"1025172426467483135","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"turbo","id":"1431694915691216896","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"turbo","id":"1431694915691216896"},"id":"1431694916265836564","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":15,"ts":"17:24:27.740"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024172426467483135-u12345-c1234567890987654321-bot:midjourney","verb":"turbo","status":"completed","created":"2025-10-24T17:24:26.467Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:24:25.528Z"},"updated":"2025-10-24T17:24:28.314Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T17:24:27.643000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"turbo","id":"1431694915691216896","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"turbo","id":"1431694915691216896"},"id":"1431694916265836564","flags":64,"embeds":[],"edited_timestamp":null,"content":"**Turbo mode enabled!** Your jobs will cost around 2x more than on `/fast` mode. Note that once you exhaust your fast hours, you can always purchase more on the website: <https://midjourney.com/account>. To conserve your fast hours, use `/relax` to switch back to relax mode.","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"relax":false,"fast":false,"turbo":true}},"code":200},"seq":17,"ts":"17:24:28.334"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Speed mode settings will be available in `response.settings` when job completes:

```typescript
settings?: {
  relax?: boolean             // Relax mode
  fast?: boolean              // Fast mode
  turbo?: boolean             // Turbo mode
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/turbo" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/turbo', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/turbo',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsTurbo() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/turbo', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsTurbo()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-variability ===
Document URL: https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-variability
## Toggle Variability Mode
<small>October 27, 2025 (January 5, 2026)</small>

---

Toggle Midjourney [Variability mode](https://docs.midjourney.com/docs/variations) using the /settings command.
> **https://api.useapi.net/v3/midjourney/jobs/variability**

### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data (required for Blob content uploads).
# Content-Type: multipart/form-data
```

### Request Body
```json
{
  "channel": "1234567890123456789"
}
```

### Parameters

- `channel` is optional if only one Midjourney account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts). You **must** specify the channel when you have multiple accounts setup and wish to use a specific account from the configured list.

- `stream` is optional (default: `true`).
  - `true` - Returns `Content-Type: text/event-stream` with live progress events. See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to retrieve updates and results

- `replyUrl` is optional. Webhook URL for real-time job event callbacks.
  All job events POST-ed to this URL as they occur.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) response.

- `replyRef` is optional. Your reference ID stored with job.  
  Returned in all responses and callbacks as `response.replyRef`.  
  Maximum length 1024 characters.

- `replyLevel` is optional (default: `all`). Controls which status changes trigger webhook callbacks.  
  - `all` - Every status change (created, started, progress, completed, failed, moderated)  
  - `standard` - Job lifecycle only (created + final states, no progress updates)  
  - `minimal` - Final outcome only (completed, failed, moderated)

### Response • JSON • `stream: false`

Response with `content-type: application/json`.

**201**
**201 Created**

Job created successfully.
Use returned `jobid` with [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid) to poll status, or wait for webhook callbacks if `replyUrl` provided.

Variability mode setting will be available in `response.settings.variability` when job completes.

```json
{
    "jobid": "j1024172338875473191-u12345-c1234567890987654321-bot:midjourney",
    "verb": "variability",
    "status": "created",
    "created": "2025-10-24T17:23:38.875Z",
    "request": {
        "replyUrl": "https://api-callback.matthieu.leblanc.workers.dev/",
        "replyRef": "2025-10-24T17:23:37.902Z",
        "stream": false
    }
}
```

**400**
**400 Bad Request**

Validation error.

```json
{
  "error": "Parameter prompt is required"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**402**
**402 Payment Required**

```json
{
  "error": "Account has no subscription or subscription expired"
}
```

**596**
**596 Pending Moderation**

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/`channel`/reset](/docs/api-midjourney-v3/post-midjourney-accounts-reset).

```json
{
  "error": "All configured Midjourney channels (2) have errors (pending moderation, CAPTCHA, etc.). Please resolve channel issues before making new requests."
}
```

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete `job` response object structure.

```bash
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024172301713382376-u12345-c1234567890987654321-bot:midjourney","seq":0,"ts":"17:23:01.728"}

data: {"event":"midjourney_created","job":{"jobid":"j1024172301713382376-u12345-c1234567890987654321-bot:midjourney","verb":"variability","status":"created","created":"2025-10-24T17:23:01.713Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:23:00.301Z"},"updated":"2025-10-24T17:23:02.780Z"},"seq":16,"ts":"17:23:02.794"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024172301713382376-u12345-c1234567890987654321-bot:midjourney","verb":"variability","status":"progress","created":"2025-10-24T17:23:01.713Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:23:00.301Z"},"updated":"2025-10-24T17:23:02.973Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T17:23:02.917000+00:00","position":0,"pinned":false,"nonce":"1025172301713382376","mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer variability","id":"1431694560119095357","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer variability","id":"1431694560119095357"},"id":"1431694560899366922","flags":192,"embeds":[],"edited_timestamp":null,"content":"","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456"}},"seq":18,"ts":"17:23:02.987"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024172301713382376-u12345-c1234567890987654321-bot:midjourney","verb":"variability","status":"completed","created":"2025-10-24T17:23:01.713Z","request":{"replyUrl":"https://api-callback.matthieu.leblanc.workers.dev/","replyRef":"2025-10-24T17:23:00.301Z"},"updated":"2025-10-24T17:23:03.611Z","response":{"webhook_id":"936929561302675456","type":20,"tts":false,"timestamp":"2025-10-24T17:23:02.917000+00:00","position":0,"pinned":false,"mentions":[],"mention_roles":[],"mention_everyone":false,"interaction_metadata":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer variability","id":"1431694560119095357","command_type":1,"authorizing_integration_owners":{"0":"0"}},"interaction":{"user":{"username":"matthieu_leblanc_975","public_flags":0,"primary_guild":null,"id":"9876543210123456789","global_name":null,"display_name_styles":null,"discriminator":"0","collectibles":null,"clan":null,"avatar_decoration_data":null,"avatar":null},"type":2,"name":"prefer variability","id":"1431694560119095357"},"id":"1431694560899366922","flags":64,"embeds":[],"edited_timestamp":null,"content":"Strong variability mode turned on! Clicking the variation buttons will now make your variations stronger! You can always turn this off by running `/prefer variability` again.","components":[],"channel_type":1,"channel_id":"1234567890987654321","author":{"username":"Midjourney Bot","public_flags":589824,"primary_guild":null,"id":"936929561302675456","global_name":null,"display_name_styles":null,"discriminator":"9282","collectibles":null,"clan":null,"bot":true,"avatar_decoration_data":null,"avatar":"b9c7b4c65e3c66f246b9a6741bd3cbe5"},"attachments":[],"application_id":"936929561302675456","settings":{"variability":true}},"code":200},"seq":21,"ts":"17:23:03.624"}

```

### Model

See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

Variability mode setting will be available in `response.settings` when job completes:

```typescript
settings?: {
  variability?: boolean       // Variation mode: true = High/Strong, false = Low/Subtle
}
```

### Examples

The examples below show the JSON response format (`stream: false`). For real-time SSE streaming examples, see the [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide).

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/variability" \
     -d '{"stream":false}'
```

**JavaScript**
``` javascript
const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/variability', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: false
  })
});

const result = await response.json();
console.log('Job created:', result.jobid);

// Poll for completion using GET /jobs/jobid
// Or use webhook with replyUrl parameter
```

**Python**
``` python
import requests

response = requests.post(
    'https://api.useapi.net/v3/midjourney/jobs/variability',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'stream': False}
)

result = response.json()
print('Job created:', result['jobid'])

# Poll for completion using GET /jobs/jobid
# Or use webhook with replyUrl parameter
```

### Try It

<script src="/assets/js/midjourney-v3.js"></script>
<script>
  async function apiExecuteJobsVariability() {
    await apiExecuteMidjourneySSE('https://api.useapi.net/v3/midjourney/jobs/variability', 'input');
  }
</script>

<form id="input" class="input-form" onsubmit="return false;">
  <div class="input-field">
    <div class="input-field-row">
      <label for="input-token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="input-token" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="input-channel"><span>channel<small> (optional - auto-selected if omitted)</small></span>
        <input id="input-channel" type="text" class="input-element input-query-param">
      </label>
      <label for="input-stream"><span>stream<small> (optional - true by default)</small></span>
        <select id="input-stream" class="input-element input-query-param">
          <option value=""></option>
          <option value="true">true (SSE streaming)</option>
          <option value="false">false</option>
        </select>
      </label>
      <label for="input-replyUrl"><span>replyUrl<small> (optional - webhook URL)</small></span>
        <input id="input-replyUrl" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyRef"><span>replyRef<small> (optional - your reference ID)</small></span>
        <input id="input-replyRef" type="text" class="input-element input-query-param">
      </label>
      <label for="input-replyLevel"><span>replyLevel<small> (optional - callback filter)</small></span>
        <select id="input-replyLevel" class="input-element input-query-param">
          <option value=""></option>
          <option value="all">all (every status), default</option>
          <option value="standard">standard (created + final)</option>
          <option value="minimal">minimal (final only)</option>
        </select>
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteJobsVariability()">Go</button>
  </div>
</form>

<div id="input-media-links" style="display:none;"></div>

<div id="input-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-midjourney-v3/quick-start ===
Document URL: https://useapi.net/docs/api-midjourney-v3/quick-start
## Quick Start
<small>October 27, 2025</small>

---

## Prerequisites

Before you begin, make sure you have:

* Active subscription - [Subscribe](/docs/start-here/setup-useapi)
* Midjourney Discord account - [Setup Midjourney](/docs/start-here/setup-midjourney)

**Important:** Same Discord account cannot be used for both v2 and v3 APIs simultaneously. If you have the account configured in v2, [delete it from v2](/docs/api-v2/del-account-midjourney-channel) first before configuring in v3. See [Migration from v2](#migration-from-v2) for details.

## Configure Your Channel

```bash
curl -X POST "https://api.useapi.net/v3/midjourney/accounts" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "discord": "YOUR_DISCORD_TOKEN",
       "maxJobs": 3,
       "maxImageJobs": 3,
       "maxVideoJobs": 3
     }'
```

See [POST /accounts](/docs/api-midjourney-v3/post-midjourney-accounts) for full documentation.

## Generate with Real-time SSE

See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for complete implementation.

## Generate with Webhook Callback

```bash
curl -X POST "https://api.useapi.net/v3/midjourney/jobs/imagine" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "a cat in a hat",
       "stream": false,
       "replyUrl": "https://your-server.com/webhook"
     }'
```

All job events will be POST-ed to your webhook URL in real-time.

## Migration from v2

**Important:** Same Discord account cannot be used for both v2 and v3 APIs simultaneously.

To migrate:
1. [Delete your Midjourney account from v2 API](/docs/api-v2/del-account-midjourney-channel)
2. [Configure the account in v3 API](/docs/api-midjourney-v3/post-midjourney-accounts)
3. Update your code to use [v3 endpoints](/docs/api-midjourney-v3)
4. Enable `stream: true` for real-time updates (recommended)

See account management endpoints:
- [POST /accounts](/docs/api-midjourney-v3/post-midjourney-accounts) - Configure channel
- [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) - List channels
- [DELETE /accounts/`channel`](/docs/api-midjourney-v3/delete-midjourney-accounts-channel) - Remove channel
  
## Next Steps

- Explore [What's New in v3](/docs/api-midjourney-v3/what-new) features
- Check [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for real-time updates

=== URL: https://useapi.net/docs/api-midjourney-v3/setup-multiple-midjourney-accounts ===
Document URL: https://useapi.net/docs/api-midjourney-v3/setup-multiple-midjourney-accounts
## How to use multiple Midjourney accounts
<small>October 27, 2025</small>

You may configure as many Discord/Midjourney accounts as desired. If more than one account is configured under [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts), the API will retrieve a list of available accounts, determine which have the capacity to execute the job, and randomly select an available account, thereby effectively acting as a load balancer.

To take advantage of saved configurations and account load balancing, please follow these simple steps:
- Gather your Midjourney account(s) information as outlined at [Setup Midjourney](/docs/start-here/setup-midjourney).
- Post your configuration(s) using the [POST /accounts](/docs/api-midjourney-v3/post-midjourney-accounts) endpoint.

To see all your currently configured Midjourney accounts, please use the [GET /accounts](/docs/api-midjourney-v3/get-midjourney-accounts) endpoint.

##### Wait there's more…

What if you want to use multiple Midjourney accounts but prefer to implement your own tracking and load balancing logic? Good news – that's still possible! Just continue providing the `channel` parameter with each API call, and our API will use the specified account. This gives you full control over which account handles each request, allowing you to implement custom load balancing or routing logic based on your specific needs.

Feel free to [reach out to us](/docs/support) if you have any questions or concerns.

=== URL: https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide ===
Document URL: https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide
## Real-Time SSE Streaming Guide
<small>October 27, 2025 (November 26, 2025)</small>

---

This guide explains how to implement real-time [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) streaming for Midjourney v3 API.

## What is SSE Streaming?

SSE streaming provides **real-time** job updates as events occur. When you set `stream: true`, the API returns a persistent connection that sends job progress events as they happen.

### Benefits
- Instant progress updates (no polling required)
- Real-time progress percentages
- Live status changes (created → started → progress → completed/failed/moderated)
- Lower latency than polling

### Connection Stability Requirements

You **must** keep the SSE connection open until the job completes. If you disconnect prematurely (before receiving `completed`, `failed`, or `moderated` status):

- Job becomes **stuck in `progress` status**
- Consumes one of your available job slots
- Prevents new jobs from starting if you're at your concurrent limit
- Remains stuck for **14 minutes** until automatic timeout

To fix stuck jobs call [DELETE /jobs/`jobId`](/docs/api-midjourney-v3/delete-midjourney-jobs-jobid) to free the job slot right away. Without manual cleanup, you must wait 14 minutes for automatic timeout.

**Common causes:** Closing browser/Postman, network interruptions, application crashes.

**Alternatives if connection stability is a concern:**
- Use webhooks: `stream: false` + `replyUrl` for fire-and-forget workflows
- Use polling: `stream: false` + `GET /jobs/{jobId}` for better connection control

## SSE Event Format

SSE responses use the `text/event-stream` content type. Each line starts with `data:` followed by a JSON object:

```
data: {"event":"initialized","message":"Stream initialized","jobId":"j1024...","seq":0,"ts":"22:41:58.458"}

data: {"event":"midjourney_created","job":{"jobid":"j1024...","verb":"imagine","status":"created",...},"seq":1,"ts":"22:41:59.123"}

data: {"event":"midjourney_progress","job":{"jobid":"j1024...","status":"progress","response":{"progress_percent":15},...},"seq":5,"ts":"22:42:10.456"}

data: {"event":"midjourney_completed","job":{"jobid":"j1024...","status":"completed","response":{...},...},"seq":8,"ts":"22:42:25.789"}
```

The following events are sent in `event` field during job execution:

| Event | Description | When Sent |
|-------|-------------|-----------|
| `initialized` | Stream initialized | First event when connection opens |
| `midjourney_created` | Job created and queued | Immediately after job creation |
| `midjourney_started` | Job processing started | When Midjourney begins processing |
| `midjourney_progress` | Progress update | During job execution (includes `progress_percent`) |
| `midjourney_completed` | Job completed successfully | When job finishes with results |
| `midjourney_failed` | Job failed | On error or timeout |
| `midjourney_moderated` | Content moderation | When prompt is flagged by Midjourney |
| `error` | General error | On unexpected errors |

### Initialized Event • `event : initialized`

```typescript
{
  event: "initialized"
  message: string            // "Stream initialized"
  jobId: string              // Job ID
  seq: number                // Sequence number (starts at 0)
  ts: string                 // Timestamp (HH:MM:SS.mmm)
}
```

### Job Lifecycle Events • `event : midjourney_*`

All other events contain the full `job` object. See [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

**Curl**
``` bash
curl -N -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://api.useapi.net/v3/midjourney/jobs/imagine" \
     -d '{"prompt":"a cat in a hat","stream":true}'
```

**Note:** The `-N` flag disables buffering for real-time streaming.

**JavaScript**
``` javascript
async function streamMidjourneyJob(prompt) {
  const response = await fetch('https://api.useapi.net/v3/midjourney/jobs/imagine', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: prompt,
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder('utf-8');
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop(); // Keep incomplete line in buffer

    for (const line of lines) {
      if (line.startsWith('data:')) {
        const data = line.slice(5).trim();
        try {
          const eventData = JSON.parse(data);
          console.log('Event:', eventData.event);

          // Handle initialized event
          if (eventData.event === 'initialized') {
            console.log('Stream initialized for job:', eventData.jobId);
            continue;
          }

          // Handle job lifecycle events
          const job = eventData.job;
          if (!job) continue;

          console.log('Job status:', job.status);

          if (job.status === 'progress') {
            console.log(`Progress: ${job.response?.progress_percent}%`);
          } else if (job.status === 'completed') {
            console.log('Job completed!', job.response);
            // Extract media URLs
            if (job.response?.attachments) {
              job.response.attachments.forEach(att => {
                console.log('Attachment:', att.url);
              });
            }
            if (job.response?.imageUx) {
              job.response.imageUx.forEach(img => {
                console.log(`Image ${img.id}:`, img.url);
              });
            }
            if (job.response?.videoUx) {
              job.response.videoUx.forEach(vid => {
                console.log(`Video ${vid.id}:`, vid.url);
              });
            }
          } else if (job.status === 'failed') {
            console.error('Job failed:', job.error);
          } else if (job.status === 'moderated') {
            console.error('Job moderated:', job.error);
          }
        } catch (e) {
          console.error('Failed to parse event data:', e);
        }
      }
    }
  }
}

// Usage
streamMidjourneyJob('a cat in a hat');
```

**Python**
``` python
import requests
import json

def stream_midjourney_job(prompt):
    url = 'https://api.useapi.net/v3/midjourney/jobs/imagine'
    headers = {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    }
    payload = {
        'prompt': prompt,
        'stream': True
    }

    response = requests.post(url, headers=headers, json=payload, stream=True)

    for line in response.iter_lines():
        if not line:
            continue

        line_str = line.decode('utf-8')

        if line_str.startswith('data:'):
            data_str = line_str[5:].strip()
            try:
                event_data = json.loads(data_str)
                print(f"Event: {event_data.get('event')}")

                # Handle initialized event
                if event_data.get('event') == 'initialized':
                    print(f"Stream initialized for job: {event_data.get('jobId')}")
                    continue

                # Handle job lifecycle events
                job = event_data.get('job')
                if not job:
                    continue

                print(f"Job status: {job.get('status')}")

                if job.get('status') == 'progress':
                    progress = job.get('response', {}).get('progress_percent', 0)
                    print(f'Progress: {progress}%')
                elif job.get('status') == 'completed':
                    print('Job completed!', job.get('response'))
                    # Extract media URLs
                    attachments = job.get('response', {}).get('attachments', [])
                    for att in attachments:
                        print(f"Attachment: {att['url']}")
                    image_ux = job.get('response', {}).get('imageUx', [])
                    for img in image_ux:
                        print(f"Image {img['id']}: {img['url']}")
                    video_ux = job.get('response', {}).get('videoUx', [])
                    for vid in video_ux:
                        print(f"Video {vid['id']}: {vid['url']}")
                elif job.get('status') == 'failed':
                    print(f"Job failed: {job.get('error')}")
                elif job.get('status') == 'moderated':
                    print(f"Job moderated: {job.get('error')}")
            except json.JSONDecodeError as e:
                print(f'Failed to parse event data: {e}')

# Usage
stream_midjourney_job('a cat in a hat')
```

## Best Practices

* **Event Handling**
   - Always check `job.status` field to determine event type
   - Handle all possible statuses: created, started, progress, completed, failed, moderated

* **Progress Updates**
   - Extract `job.response.progress_percent` for visual feedback (if provided - not always present)
   - Update UI in real-time as events arrive

* **Media Extraction**
   - Access `job.response.buttons` for available actions
   - Parse `job.response.attachments` for generated images/videos
   - Use `job.response.imageUx` and `job.response.videoUx` for upscaled media from `https://cdn.midjourney.com`. See [GET /proxy/cdn-midjourney](/docs/api-midjourney-v3/get-proxy-cdn-midjourney) to retrieve `imageUx`/`videoUx` assets via useapi.net proxy

* **Error Handling**
   - Always implement proper error handling for SSE streams
   - Check response status before processing stream
   - Catch JSON parse errors gracefully
   - Implement retry logic or fall back to polling (GET /jobs/`jobid`) if SSE fails

## Alternative: Webhook Callbacks

If you prefer server-to-server notifications instead of client SSE streams, use the `replyUrl` parameter whit `stream: false`:

```json
{
  "prompt": "a cat in a hat",
  "stream": false,
  "replyUrl": "https://your-server.com/webhook"
}
```

All job events will be **POST**ed to your webhook URL in real-time using `content: application/json` format, see [Job Response Model](/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete job events structure.

=== URL: https://useapi.net/docs/api-midjourney-v3/vary-region-mask-editor ===
Document URL: https://useapi.net/docs/api-midjourney-v3/vary-region-mask-editor
## Simple Vary Region (inpaint) mask editor
<small>October 27, 2025 (February 19, 2026)</small>

Midjourney inpainting [Vary Region](https://docs.midjourney.com/docs/vary-region) and [Vary Region + Remix](https://docs.midjourney.com/docs/vary-region-remix) button require a base64-encoded black and white WebP mask image. The generated base64 mask value is used by the [POST /jobs/button](/docs/api-midjourney-v3/post-midjourney-jobs-button#request-body) button `Vary (Region)` param `mask`.

{% raw %}

<style>
    #canvasContainer {
        position: relative;
        max-width: 100vw;
        max-height: 100vh;
        /* overflow: hidden; */
        margin: 0 auto;
    }
    #imageCanvas, #maskCanvas {
        display: block;
    }
    #imageCanvas {
        border: 1px solid #ccc;
    }
    #maskCanvas {
        position: absolute;
        left: 0;
        top: 0;
        cursor: crosshair;
    }
    #maskBase64 {
        width: 100%;
        height: 100px;
        margin-top: 10px;
    }
    #copyMaskButton {
        margin-top: 10px;
    }
</style>

<input type="file" id="imageLoader" name="imageLoader"/>
<div id="canvasContainer">
    <canvas id="imageCanvas"></canvas>
    <canvas id="maskCanvas"></canvas>
</div>
<button id="copyMaskButton">Copy Base64 to Clipboard</button>
<textarea id="maskBase64" readonly></textarea>

<script>
    function getMousePos(canvas, evt) {
        var rect = canvas.getBoundingClientRect();
        var scaleX = canvas.width / rect.width;
        var scaleY = canvas.height / rect.height;
        return {
            x: (evt.clientX - rect.left) * scaleX,
            y: (evt.clientY - rect.top) * scaleY
        }
    }

    document.addEventListener('DOMContentLoaded', () => {
        var isDrawing = false;
        var rect = {};
        var img = new Image();
        var base64Mask = '';

        var imageLoader = document.getElementById('imageLoader');
        var canvasContainer = document.getElementById('canvasContainer');
        var copyMaskButton = document.getElementById('copyMaskButton');
        var maskBase64 = document.getElementById('maskBase64');
        var imageCanvas = document.getElementById('imageCanvas');
        var maskCanvas = document.getElementById('maskCanvas');
        var imageCtx = imageCanvas.getContext('2d');
        var maskCtx = maskCanvas.getContext('2d');

        var viewportWidth = window.innerWidth;
        var rectCanvasContainer = canvasContainer.getBoundingClientRect();
        var viewportHeight = window.innerHeight - rectCanvasContainer.top + window.scrollY;

        imageLoader.addEventListener('change', function(e) {
            var reader = new FileReader();
            reader.onload = function(event) {
                img.onload = function() {
                    var widthScale = viewportWidth / img.width;
                    var heightScale = viewportHeight / img.height;
                    var scale = Math.min(widthScale, heightScale, 1);
                    var scaledWidth = img.width * scale;
                    var scaledHeight = img.height * scale;

                    imageCanvas.width = img.width;
                    imageCanvas.height = img.height;
                    maskCanvas.width = img.width;
                    maskCanvas.height = img.height;

                    imageCanvas.style.width = scaledWidth + 'px';
                    imageCanvas.style.height = scaledHeight + 'px';
                    maskCanvas.style.width = scaledWidth + 'px';
                    maskCanvas.style.height = scaledHeight + 'px';

                    imageCtx.drawImage(img, 0, 0);
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);

                    maskBase64.value = '';
                    base64Mask = '';

                    isDrawing = false;
                    rect = {};
                };

                img.src = event.target.result;

            };

            reader.readAsDataURL(e.target.files[0]);

        }, false);

        maskCanvas.addEventListener('mousedown', function(e) {
            isDrawing = true;
            rect = {};
            var pos = getMousePos(maskCanvas, e);
            rect.startX = pos.x;
            rect.startY = pos.y;
            rect.w = 0;
            rect.h = 0;
            maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
        });

        maskCanvas.addEventListener('mousemove', function(e) {
            if (isDrawing) {
                var pos = getMousePos(maskCanvas, e);
                rect.w = pos.x - rect.startX;
                rect.h = pos.y - rect.startY;
                maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                maskCtx.strokeStyle = 'red';
                maskCtx.lineWidth = 2;
                maskCtx.strokeRect(rect.startX, rect.startY, rect.w, rect.h);
            }
        });

        maskCanvas.addEventListener('mouseup', function(e) {
            if (isDrawing) {
                isDrawing = false;
                var rectWidth = Math.abs(rect.w);
                var rectHeight = Math.abs(rect.h);

                if (rectWidth > 1 && rectHeight > 1) {
                    var maskImage = document.createElement('canvas');
                    maskImage.width = maskCanvas.width;
                    maskImage.height = maskCanvas.height;
                    var maskImageCtx = maskImage.getContext('2d');
                    maskImageCtx.fillStyle = '#000';
                    maskImageCtx.fillRect(0, 0, maskImage.width, maskImage.height);
                    var drawX = rect.w >= 0 ? rect.startX : rect.startX + rect.w;
                    var drawY = rect.h >= 0 ? rect.startY : rect.startY + rect.h;
                    maskImageCtx.fillStyle = '#fff';
                    maskImageCtx.fillRect(drawX, drawY, rectWidth, rectHeight);
                    var base64String = maskImage.toDataURL('image/webp');
                    base64Mask = base64String.replace(/^data:image\/webp;base64,/, '');
                    maskBase64.value = base64Mask;
                } else {
                    maskBase64.value = '';
                    base64Mask = '';
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                }
            }
        });

        copyMaskButton.addEventListener('click', function() {
            if (base64Mask) {
                maskBase64.select();
                maskBase64.setSelectionRange(0, maskBase64.value.length);
                try {
                    var successful = document.execCommand('copy');
                    if (successful) {
                        alert('✅ Base64 mask copied to clipboard!');
                    } else {
                        alert('🛑 Failed to copy base64 mask.');
                    }
                } catch (err) {
                    alert('🛑 Oops, unable to copy');
                }
            } else {
                alert('🛑 No base64 mask to copy. Please select a valid rectangle.');
            }
        });
    });
</script>

{% endraw %}

<details markdown="block">

<summary><small>Source code</small></summary>

Copy the code provided below into a `<select desired file name>.html` and open it in your browser.

```html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Simple Vary Region (inpaint) mask editor</title>

<style>
    #canvasContainer {
        position: relative;
        max-width: 100vw;
        max-height: 100vh;
        /* overflow: hidden; */
        margin: 0 auto;
    }
    #imageCanvas, #maskCanvas {
        display: block;
    }
    #imageCanvas {
        border: 1px solid #ccc;
    }
    #maskCanvas {
        position: absolute;
        left: 0;
        top: 0;
        cursor: crosshair;
    }
    #maskBase64 {
        width: 100%;
        height: 100px;
        margin-top: 10px;
    }
    #copyMaskButton {
        margin-top: 10px;
    }
</style>

<input type="file" id="imageLoader" name="imageLoader"/>
<div id="canvasContainer">
    <canvas id="imageCanvas"></canvas>
    <canvas id="maskCanvas"></canvas>
</div>
<button id="copyMaskButton">Copy Base64 to Clipboard</button>
<textarea id="maskBase64" readonly></textarea>

<script>
    function getMousePos(canvas, evt) {
        var rect = canvas.getBoundingClientRect();
        var scaleX = canvas.width / rect.width;
        var scaleY = canvas.height / rect.height;
        return {
            x: (evt.clientX - rect.left) * scaleX,
            y: (evt.clientY - rect.top) * scaleY
        }
    }

    document.addEventListener('DOMContentLoaded', () => {
        var isDrawing = false;
        var rect = {};
        var img = new Image();
        var base64Mask = '';

        var imageLoader = document.getElementById('imageLoader');
        var canvasContainer = document.getElementById('canvasContainer');
        var copyMaskButton = document.getElementById('copyMaskButton');
        var maskBase64 = document.getElementById('maskBase64');
        var imageCanvas = document.getElementById('imageCanvas');
        var maskCanvas = document.getElementById('maskCanvas');
        var imageCtx = imageCanvas.getContext('2d');
        var maskCtx = maskCanvas.getContext('2d');

        var viewportWidth = window.innerWidth;
        var rectCanvasContainer = canvasContainer.getBoundingClientRect();
        var viewportHeight = window.innerHeight - rectCanvasContainer.top + window.scrollY;

        imageLoader.addEventListener('change', function(e) {
            var reader = new FileReader();
            reader.onload = function(event) {
                img.onload = function() {
                    var widthScale = viewportWidth / img.width;
                    var heightScale = viewportHeight / img.height;
                    var scale = Math.min(widthScale, heightScale, 1);
                    var scaledWidth = img.width * scale;
                    var scaledHeight = img.height * scale;

                    imageCanvas.width = img.width;
                    imageCanvas.height = img.height;
                    maskCanvas.width = img.width;
                    maskCanvas.height = img.height;

                    imageCanvas.style.width = scaledWidth + 'px';
                    imageCanvas.style.height = scaledHeight + 'px';
                    maskCanvas.style.width = scaledWidth + 'px';
                    maskCanvas.style.height = scaledHeight + 'px';

                    imageCtx.drawImage(img, 0, 0);
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);

                    maskBase64.value = '';
                    base64Mask = '';

                    isDrawing = false;
                    rect = {};
                };

                img.src = event.target.result;

            };

            reader.readAsDataURL(e.target.files[0]);

        }, false);

        maskCanvas.addEventListener('mousedown', function(e) {
            isDrawing = true;
            rect = {};
            var pos = getMousePos(maskCanvas, e);
            rect.startX = pos.x;
            rect.startY = pos.y;
            rect.w = 0;
            rect.h = 0;
            maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
        });

        maskCanvas.addEventListener('mousemove', function(e) {
            if (isDrawing) {
                var pos = getMousePos(maskCanvas, e);
                rect.w = pos.x - rect.startX;
                rect.h = pos.y - rect.startY;
                maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                maskCtx.strokeStyle = 'red';
                maskCtx.lineWidth = 2;
                maskCtx.strokeRect(rect.startX, rect.startY, rect.w, rect.h);
            }
        });

        maskCanvas.addEventListener('mouseup', function(e) {
            if (isDrawing) {
                isDrawing = false;
                var rectWidth = Math.abs(rect.w);
                var rectHeight = Math.abs(rect.h);

                if (rectWidth > 1 && rectHeight > 1) {
                    var maskImage = document.createElement('canvas');
                    maskImage.width = maskCanvas.width;
                    maskImage.height = maskCanvas.height;
                    var maskImageCtx = maskImage.getContext('2d');
                    maskImageCtx.fillStyle = '#000';
                    maskImageCtx.fillRect(0, 0, maskImage.width, maskImage.height);
                    var drawX = rect.w >= 0 ? rect.startX : rect.startX + rect.w;
                    var drawY = rect.h >= 0 ? rect.startY : rect.startY + rect.h;
                    maskImageCtx.fillStyle = '#fff';
                    maskImageCtx.fillRect(drawX, drawY, rectWidth, rectHeight);
                    var base64String = maskImage.toDataURL('image/webp');
                    base64Mask = base64String.replace(/^data:image\/webp;base64,/, '');
                    maskBase64.value = base64Mask;
                } else {
                    maskBase64.value = '';
                    base64Mask = '';
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                }
            }
        });

        copyMaskButton.addEventListener('click', function() {
            if (base64Mask) {
                maskBase64.select();
                maskBase64.setSelectionRange(0, maskBase64.value.length);
                try {
                    var successful = document.execCommand('copy');
                    if (successful) {
                        alert('✅ Base64 mask copied to clipboard!');
                    } else {
                        alert('🛑 Failed to copy base64 mask.');
                    }
                } catch (err) {
                    alert('🛑 Oops, unable to copy');
                }
            } else {
                alert('🛑 No base64 mask to copy. Please select a valid rectangle.');
            }
        });
    });
</script>

</body>
</html>

```

</details>

=== URL: https://useapi.net/docs/api-midjourney-v3/what-new ===
Document URL: https://useapi.net/docs/api-midjourney-v3/what-new
## What's New in v3
<small>October 27, 2025</small>

---

### Real-time SSE Streaming

Get instant progress updates with `stream: true`:
- No polling required - events arrive in real-time
- Live progress percentages as jobs execute
- Immediate status notifications (created → started → progress → completed/moderated/failed)
- See [SSE Streaming Guide](/docs/api-midjourney-v3/sse-streaming-guide) for implementation details

### Real-time Webhook Callbacks

Receive job events at your server with `replyUrl`:
- Works with **both** `stream: true` and `stream: false`
- All events POST-ed instantly to your webhook URL
- Ideal for server-to-server integrations
- No client connection required

### Flexible Request Formats

Send requests as JSON or multipart/form-data:
- `Content-Type: application/json` - Simple JSON payloads
- `Content-Type: multipart/form-data` - File uploads (describe, blend)

### Settings Command Support

Full support for Midjourney settings commands with structured response parsing:
- [POST /jobs/settings](/docs/api-midjourney-v3/post-midjourney-jobs-settings) - View all current settings (version, stylize, RAW, personalization, public/private, remix, variability, speed modes, suffix)
- [POST /jobs/info](/docs/api-midjourney-v3/post-midjourney-jobs-info) - Account info with speed mode settings
- [POST /jobs/fast](/docs/api-midjourney-v3/post-midjourney-jobs-fast), [/relax](/docs/api-midjourney-v3/post-midjourney-jobs-relax), [/turbo](/docs/api-midjourney-v3/post-midjourney-jobs-turbo) - Toggle speed modes
- [POST /jobs/remix](/docs/api-midjourney-v3/post-midjourney-jobs-remix), [/variability](/docs/api-midjourney-v3/post-midjourney-jobs-variability) - Toggle mode settings
- All settings responses include `response.settings` object with explicit values

### Separate Image/Video Quotas

Better resource management with independent limits:
- `maxImageJobs` - Concurrent image generation limit
- `maxVideoJobs` - Concurrent video generation limit
- Optimized for mixed workloads

### Execute-Once Pattern

U1-U4 upscale buttons and seed retrieval can only be executed once per job:
- Prevents accidental duplicate upscales and redundant seed requests
- Subsequent requests return existing result immediately
- Cleaner job tracking and efficient resource usage

### Parent-Child Job Tracking

Jobs automatically track their children:
- `response.children` shows all child jobs
- Easy navigation through job hierarchies
- Track imagine → upscale → variations workflows

### Enhanced Error Handling

More specific HTTP status codes:
- `410` - Job expired (older than 62 days)
- `596` - Moderation/CAPTCHA required (with email notification)

### Classic Polling Available

Traditional polling still supported via [GET /jobs/`jobid`](/docs/api-midjourney-v3/get-midjourney-jobs-jobid):
- Use as fallback when SSE/webhooks unavailable
- Returns same job data as SSE events
- Last resort approach - prefer SSE or webhooks

=== URL: https://useapi.net/docs/start-here/setup-minimax ===
Document URL: https://useapi.net/docs/start-here/setup-minimax
# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png"> Setup MiniMax | Hailuo AI
<small>September 25, 2024 (November 24, 2025)</small>

## Table of contents
<small>Approximately 5 minutes to complete setup steps.</small>  

---
> This is the setup guide for [MiniMax API](/docs/api-minimax-v1). A [Hailuo AI](https://hailuoai.video) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

## Setup <b>hailuoai.video</b> account

You need a [hailuoai.video](https://hailuoai.video) account to to use MiniMax API. Sign-in with your Google account at [hailuoai.video](https://hailuoai.video). You can create as many accounts as you need. Our API uses automated load balancing and will select an account with available capacity.

### Step 1 • Navigate to hailuoai.video

Open Chromium-compatible browser (e.g. [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/en-us/edge) or [Opera](https://www.opera.com/)) and navigate to [https://hailuoai.video](https://hailuoai.video). 

Once the page is fully loaded, ensure that you're logged in with your Google account <span style="color: red;">`1`</span>.

Open [Developer Tools](https://developer.chrome.com/docs/devtools) by right-clicking on the page and selecting "Inspect Element" <span style="color: red;">`2`</span>.

Finally refresh page <span style="color: red;">`3`</span>.

![](/assets/images/minimax_video_setup_1.png)

### Step 2 • Locate `url`

Select Developer Tools » Network <span style="color: red;">`1`</span>:  
* On the left side many click on  `Assets` submenu <span style="color: red;">`2`</span>.  
* Type `/cursor` in the filter box <span style="color: red;">`3`</span> and hit Enter.  
* Make sure that `All`  or `Fetch/XHR` is selected <span style="color: red;">`4`</span>.  
* You should see a http call(s) entry as shown below <span style="color: red;">`5`</span>, click on that entry.  
* Select "Headers" tab <span style="color: red;">`6`</span>.  
* Locate General » Request URL <span style="color: red;">`7`</span> as shown below and copy its value. This is your `url`.

[EXPAND](/assets/images/minimax_video_setup_2.png){:target="_blank"}
![](/assets/images/minimax_video_setup_2.png)

As an example below the `url` is 

```
https://hailuoai.video/v3/api/multimodal/video/my/cursor?type=next&currentID=0&limit=30&scene=mine&filterType=2&device_platform=web&app_id=3001&version_code=22202&biz_id=0&lang=en&uuid=8a2d8b5d-ac0d-4bb5-8028-3177fa64f861&device_id=301350748241866752&os_name=Windows&browser_name=opera&device_memory=8&cpu_core_num=12&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1728704107000
```

### Step 3 • Locate `token` value

Locate Request Headers » Token <span style="color: red;">`7`</span> as shown below and copy it's value. This is your `token`.  

[EXPAND](/assets/images/minimax_video_setup_3.png){:target="_blank"}
![](/assets/images/minimax_video_setup_3.png)

As an example below the `token` is 

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzIxNTk4MjksInVzZXIiOnsiaWQiOiIzMDEzNDg0MDk1ODE4MzgzMzYiLCJuYW1lIjoidXNlIGFwaSIsImF2YXRhciI6Imh0dHBzOi8vbGgzLmdvb2dsZXVzZXJjb250ZW50LmNvbS9hL0FDZzhvY0lLNEJaMmpfSlIxcTh3TkFKU2RlZzlwVHZlTDJTSVhFRjg4TkU4MV85VlowbFBRQT1zOTYtYyIsImRldmljZUlEIjoiIn19.1-zGnbUfENnVdjDGDBuaZ4Sf7rTelfqUKk5XNj7liE4
```

If you are curious, you can use [jwt.io](https://jwt.io) to decode the token and see its content.

## Verify and add account

Use the form below to verify your credentials and add your MiniMax account.

Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) directly.

<script>
  async function apiTestAccountMiniMax(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-MiniMax-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let url = document.getElementById(`post-accounts-MiniMax-url`)?.value;
      let token = document.getElementById(`post-accounts-MiniMax-token`)?.value;

      url = url && url.length ? url : undefined;
      token = token && token.length ? token : undefined;

      const body = { token, url, maxJobs: 3 };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/minimax/accounts`, 'post-accounts-MiniMax', data);
  }
</script>

<form id="post-accounts-MiniMax" onsubmit="apiTestAccountMiniMax(document.getElementById('post-accounts-MiniMax-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-MiniMax-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-MiniMax-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-url"><span>url&nbsp;&nbsp;&nbsp;</span>
        <input id="post-accounts-MiniMax-url" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-token"><span>token</span>
        <input id="post-accounts-MiniMax-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-action"><span>action</span>
        <select id="post-accounts-MiniMax-action" class="input-element">
          <option value="verify">Verify — test credentials only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-MiniMax-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-MiniMax-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-minimax-v1 ===
Document URL: https://useapi.net/docs/api-minimax-v1

# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png"> MiniMax API v1

<small>September 25, 2024 (May 13, 2026)</small>

This is [experimental](/docs/legal) API for for the [MiniMax AI](https://minimaxi.com), a Chinese AI startup backed by Alibaba and Tencent. 

We provide full API support for following MiniMax/Hailuo AI models:
* MiniMax [videos](api-minimax-v1/post-minimax-videos-create) supports 17 models across 4 families: [Hailuo 01/02/2.3](https://hailuoai.video), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2](https://openai.com/sora/), and [Seedance 2.0/Fast](https://seed.bytedance.com/). These models are notable for generating ultra-realistic video clips with precise prompt following.
* MiniMax [images](api-minimax-v1/post-minimax-images-create) supports 9 models: [Midjourney V7](https://www.midjourney.com/), [Midjourney NiJi 7](https://www.midjourney.com/), [Nano Banana 2](https://hailuoai.video), [Nano Banana Pro](https://blog.google/technology/ai/nano-banana-pro/), [GPT Image 1.5](https://openai.com/index/introducing-4o-image-generation/), [GPT Image 2](https://openai.com/index/introducing-4o-image-generation/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), and image-01.
* MiniMax [agent](api-minimax-v1/post-minimax-agent) supports multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2](https://openai.com/sora/)), image generation ([Midjourney V7/NiJi 7](https://www.midjourney.com/), [Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)).
  
Nano Banana 2/Pro deployment provided by MiniMax has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people.

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing. With the [$79.99/m](https://hailuoai.video/subscribe/modal) Master account (12,000 credits), you can generate ~12,000 songs or up to 12,000 images.

**Images** — per image, see [images/create](api-minimax-v1/post-minimax-images-create) for details

| Model | Credits |
|:------|:-------:|
| image-01 | 1 |
| midjourney-v7, midjourney-niji7 | 3 |
| seedream-4.5, seedream-5.0 | 4 |
| nano-banana-2 (512P/1K) | 4 |
| nano-banana-2 (2K) | 5 |
| nano-banana-2 (4K) | 8 |
| nano-banana-pro (1K/2K) | 6 |
| nano-banana-pro (4K) | 10 |
| gpt-image-1.5 (Low/Medium/High) | 4 / 8 / 15 |
| gpt-image-2 quality `low` (1K/2K/4K) | 2 / 5 / 10 |
| gpt-image-2 quality `medium` (1K/2K/4K) | 8 / 20 / 40 |
| gpt-image-2 quality `high` (1K/2K/4K) | 30 / 80 / 160 |

**Videos** — per video, see [videos/create](api-minimax-v1/post-minimax-videos-create) for details

| Model | Credits |
|:------|:-------:|
| Hailuo 01 (all models) | 25 |
| 02, T2V-2.3, I2V-2.3 (768p/1080p) | 25-80 |
| I2V-2.3-Fast (768p/1080p) | 15-50 |
| Sora-2 (4/8/12sec) | 40 / 80 / 120 |
| Veo-3.1, Veo-3.1-S2V (720p/1080p/4K) | 120 / 120 / 180 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast (720p/1080p/4K) | 60 / 60 / 90 |
| Seedance-2.0-Fast 480p / 720p (T2V, per second) | 4 / 10 |
| Seedance-2.0-Fast 480p / 720p (I2V or omni, per second) | 7 / 15 |
| Seedance-2.0 480p / 720p / 1080p (T2V, per second) | 5 / 12 / 27 |
| Seedance-2.0 480p / 720p / 1080p (I2V or omni, per second) | 9 / 19 / 45 |

**Audio** — 1 credit per song

</details>

[Setup MiniMax](/docs/start-here/setup-minimax)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(May 13, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-minimax-v1.txt) <small>Feed this to your LLM to build integrations</small>

[Q&A: How is your experimental MiniMax API different from the official MiniMax API?](/docs/questions-and-answers#how-is-your-experimental-minimax-api-different-from-the-official-minimax-api)

Blogs:
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [Nano Banana 2](/blog/260227)
* [MiniMax Sora 2 & Midjourney V7](/blog/260224)
* [MiniMax Sora 2, Veo 3.1](/blog/260102)
* [MiniMax Agent: Nano Banana 2/Pro, Speech 2.5, Music 2.0 and more...](/blog/251124)
* [MiniMax 2.3](/blog/251030)
* [MiniMax 02 End Frame](/blog/250830)
* [Groundbreaking Video Agents](/blog/250630)
* [MiniMax Images](/blog/250508)

Articles:
* [Fun with MiniMax API](/docs/articles/minimax-bash)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/minimax_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/minimax_api</a>

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account
## Delete MiniMax API account
<small>September 25, 2024 (March 17, 2025)</small>

---
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/minimax/accounts/<account> 
```

**JavaScript**
``` javascript
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Previously configured account" 
apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-audio-audio_id ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-audio-audio_id
## Delete text-to-speech audio clip 
<small>December 27, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint will delete audio clip generated by 

* [POST audio/create-mp3](/docs/api-minimax-v1/post-minimax-audio-create-mp3)
* [POST audio/create-stream](/docs/api-minimax-v1/post-minimax-audio-create-stream)

This endpoint will return a response `200` if you're trying to delete a audio clip that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/audio/`audio_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify the audio_id you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/audio/<audio_id>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const audio_id = "audio_id to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/${audio_id}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
audio_id = "audio_id to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/{audio_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID
## Delete file
<small>December 23, 2024</small>

---

Use this endpoint to delete file uploaded by

* [POST files](/docs/api-minimax-v1/post-minimax-files)

This endpoint will return a response `200` if you're trying to delete a file that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/files/`fileID`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `fileID` is **required**. Specify the fileID you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/files/fileID" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const fileID = "fileID to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/${fileID}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
fileID = "fileID to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/files/{fileID}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId
## Delete image 
<small>March 17, 2025</small>

---

Use this endpoint to delete image generated by

* [POST images/create](/docs/api-minimax-v1/post-minimax-images-create)

This endpoint will return a response `200` if you're trying to delete a image that does not exist or has already been deleted. It is safe to say it always succeeds.

Images are soft-deleted. While the image will no longer appear in [GET images](/docs/api-minimax-v1/get-minimax-images), you can still retrieve it via [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId).
> **https://api.useapi.net/v1/minimax/images/`imageId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/images/<imageId>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const imageId = "imageId to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
imageId = "imageId to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-llm
## Delete LLM chats and/or messages
<small>March 7, 2025 (November 24, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax LLM has been decommissioned and will be replaced with upcoming Google AI and Gemini support.</b></span>

---

Equivalent of [chat.minimax.io](https://chat.minimax.io).

Use your [chat.minimax.io](https://chat.minimax.io) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/llm/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `chatIDs` is optional, specify comma-separated list of chatID values that you want to delete. Set it to `all` to delete all chats for your account.  
 
- `msgIDs` is optional, specify a comma-separated list of msgID values that you want to delete.  

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/llm/?account=<account>&msgID=<msgID>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const msgID = "Message msgID you want to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/llm/?account=${account}&msgID=${msgID}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
msgID = "Message msgID you want to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/llm/?account={account}&msgID={msgID}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId
## Remove video or image generation from being tracked by the scheduler
<small>September 25, 2024 (March 17, 2025)</small>

---

API tracks the running generations of images and videos. This is done to maintain a list of currently executed video generations and to send webhook messages via optionally provided `replyUrl` parameters. If you want to remove image or video generation from being tracked by the scheduler, use this endpoint.
> **https://api.useapi.net/v1/minimax/scheduler/`id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `id` is **required**. Specify videoId or imageId you want to stop tracking.

##### Responses 

**204**
**204 No Content**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Unable to locate running <id>"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v1/minimax/scheduler/<id>" 
```

**JavaScript**
``` javascript
const videoId = "videoId to cancel"; 
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/${videoId}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoId = "videoId to cancel" 
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/{videoId}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId
## Delete video 
<small>December 23, 2024</small>

---

Use this endpoint to delete video generated by

* [videos/create](/docs/api-minimax-v1/post-minimax-videos-create)

This endpoint will return a response `200` if you're trying to delete a video that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/videos/`videoId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/videos/videoId" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const videoId = "videoId to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
videoId = "videoId to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account
## Retrieve MiniMax API account configuration for `account` 
<small>September 25, 2024 (March 17, 2025)</small>

---
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "account": "123456",
    "jwt": {
        "token": "abc…secured…xyz",
        "user": {
            "deviceID": "123456789",
            "id": "123456",
            "isAnonymous": true,
            "name": "<name>",
            "avatar": "<url>"
        },
        "exp": 1734858598.864,
        "iat": 1732266598.864,
        "host": "hailuoai.video",
        "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
        "iat_Issued": "2024-01-01T00:00:00.000Z",
        "exp_Expire": "2024-12-01T00:00:00.000Z"
    },
    "maxJobs": 1,
    "supportVideo": true,
    "supportChat": true,
    "supportAudio": true
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  account: string
  jwt: {
    token: string
    user: {
      deviceID: string
      id: string
      isAnonymous: boolean
      name: string
      avatar: string
    },
    exp: number
    iat: number
    host: string
    searchParams: string
    iat_Issued: string
    exp_Expire: string
  }
  maxJobs: number
  supportVideo: boolean 
  supportChat: boolean 
  supportAudio: boolean 
  supportMusic: boolean
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/minimax/accounts/<account> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts
## Retrieve MiniMax API accounts configuration
<small>September 25, 2024 (March 17, 2025)</small>

---

For your convenience, you can specify your MiniMax configuration values under your MiniMax account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax.

This endpoint retrieves the complete list of configured API accounts for MiniMax.
> **https://api.useapi.net/v1/minimax/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "123456": {
        "account": "123456",
        "jwt": {
            "token": "abc…secured…xyz",
            "user": {
                "deviceID": "123456789",
                "id": "123456",
                "isAnonymous": true,
                "name": "<name>",
                "avatar": "<url>"
            },
            "exp": 1734858598.864,
            "iat": 1732266598.864,
            "host": "hailuoai.video",
            "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
            "iat_Issued": "2024-01-01T00:00:00.000Z",
            "exp_Expire": "2024-12-01T00:00:00.000Z"
        },
        "maxJobs": 1,
        "supportVideo": true,
        "supportChat": true,
        "supportAudio": true
    },
    "78910": {
        "account": "78910",
        "jwt": {
            "token": "edf…secured…lmn",
            "user": {
                "deviceID": "987654321",
                "id": "78910",
                "isAnonymous": true,
                "name": "<name>",
                "avatar": "<url>"
            },
            "host": "hailuoai.com",
            "exp": 1744858598.864,
            "iat": 1742266598.864,
            "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=92f1a65c-3e9e-4a37-8bd7-8615a6cf60ee&device_id=987654321&os_name=Windows&browser_name=firefox&device_memory=16&cpu_core_num=8&browser_language=en-US&browser_platform=Win64&screen_width=2560&screen_height=1440&unix=1742266598000",
            "iat_Issued": "2025-01-01T00:00:00.000Z",
            "exp_Expire": "2025-12-01T00:00:00.000Z"
        },
        "maxJobs": 1,
        "supportVideo": true,
        "supportChat": true,
        "supportAudio": true
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    [account: string]: {
        account: string
        jwt: {
            token: string
            user: {
                deviceID: string
                id: string
                isAnonymous: boolean
                name: string
                avatar: string
            },
            exp: number
            iat: number
            host: string
            searchParams: string
            iat_Issued: string
            exp_Expire: string
        }
        maxJobs: number
        supportVideo: boolean 
        supportChat: boolean 
        supportAudio: boolean 
        supportMusic: boolean
    }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/minimax/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/minimax/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/minimax/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId
## Retrieve Agent Job Status and Results
<small>November 24, 2025 (November 26, 2025)</small>

---

Retrieve the status and results of an agent job. Jobs are stored for 31 days after creation.

Use this endpoint to check the progress of asynchronous agent jobs created with [POST agent](/docs/api-minimax-v1/post-minimax-agent) using `async: true`.
> **https://api.useapi.net/v1/minimax/agent/`jobId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `jobId` is **required**. The job ID to query.

##### Responses

**200**
**200 OK**

Job found and returned successfully.

**Started Job:**
```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "started",
    "created": "2025-11-23T12:34:56.789Z",
    "request": {
        "prompt": "Generate a video of a cat playing piano",
        "models": ["hailuo-2.3"],
        "async": true
    }
}
```

**Completed Job:**
```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "completed",
    "created": "2025-11-23T12:34:56.789Z",
    "request": {
        "prompt": "Generate a video of a cat playing piano",
        "models": ["hailuo-2.3", "nano-banana-2"]
    },
    "response": {
        "projectID": "123456789",
        "sectionID": "987654321",
        "chatID": "456789123",
        "msg_content": "I've generated a video of a cat playing piano and an image variation.",
        "timestamp": 1732366496789,
        "elapsedTime": "02:15",
        "attachments": [
            {
                "attachmentID": "att_123456789",
                "type": 1,
                "status": 3,
                "file": {
                    "fileName": "cat_piano_video.mp4",
                    "fileUrl": "https://cdn.hailuoai.video/...mp4",
                    "type": "video/mp4",
                    "extra": {
                        "width": "1280",
                        "height": "720",
                        "duration": "5.0",
                        "fps": "24",
                        "no_watermark_url": "https://cdn.hailuoai.video/.../no_watermark.mp4",
                        "watermark_url": "https://cdn.hailuoai.video/.../watermark.mp4",
                        "thumbnail_url": "https://cdn.hailuoai.video/.../thumb.jpg"
                    }
                }
            },
            {
                "attachmentID": "att_987654321",
                "type": 2,
                "status": 3,
                "file": {
                    "fileName": "cat_piano_image.png",
                    "fileUrl": "https://cdn.hailuoai.video/...png",
                    "type": "image/png",
                    "extra": {
                        "model_name": "banana_2",
                        "model_aspect_ratio": "16:9",
                        "model_resolution": "1K"
                    }
                }
            }
        ]
    }
}
```

**Failed Job:**
```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "failed",
    "created": "2025-11-23T12:34:56.789Z",
    "request": {
        "prompt": "Generate a video",
        "models": ["hailuo-2.3"]
    },
    "error": {
        "message": "Timeout waiting for assistant response",
        "status": 504
    }
}
```

**400**
**400 Bad Request**

Invalid job ID format or access denied.

```json
{
  "error": "Error …",
  "code": 400
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Job not found or expired after 31 days.

```json
{
  "error": "Job not found or expired after 31 days",
  "code": 404
}
```

##### Model

**Downloading Generated Files:**
- `file.fileUrl` - Primary download URL (may have watermark)
- `file.extra.no_watermark_url` - URL without watermark (when available)
- `file.extra.watermark_url` - URL with watermark
- `node.agentFile.noWatermarkUrl` - Alternative watermark-free URL
- `node.agentFile.url` - Alternative file URL

```typescript
{
  // Job metadata
  jobId: string                      // Unique job identifier
  status: 'started' | 'completed' | 'failed'  // Job status
  created: string                    // ISO 8601 timestamp
  code?: number                      // HTTP status code (optional)

  // Original request
  request: {
    prompt: string                   // User's prompt
    file?: Array<{                   // File metadata (actual files not included)
      name: string
      size: number
      type: string
    }>
    models: string[]                 // Model IDs used
    async?: boolean                  // Async mode flag
    replyUrl?: string               // Callback URL
    replyRef?: string               // User's reference ID
  }

  // Agent response (only present when status is 'completed')
  response?: {
    projectID: string                // MiniMax project ID
    sectionID: string                // MiniMax section ID
    chatID: string                   // MiniMax chat ID
    msg_content: string              // Agent's response message
    timestamp: number                // Response timestamp (milliseconds since epoch)
    elapsedTime: string              // Elapsed time (mm:ss format)
    attachments?: Array<{            // Generated files
      attachmentID: string           // Attachment identifier
      type: number                   // Attachment type (numeric)
      status: number                 // Attachment status (3 = completed)
      file: {
        fileName: string             // File name
        fileUrl: string              // CDN URL to download file
        extra?: {                    // Additional file metadata
          // Video-specific fields
          height?: string            // Video height in pixels
          width?: string             // Video width in pixels
          duration?: string          // Duration in seconds
          fps?: string               // Frames per second
          frames?: string            // Total frame count
          no_watermark_url?: string  // CDN URL without watermark
          watermark_url?: string     // CDN URL with watermark
          thumbnail_url?: string     // Thumbnail image URL
          url?: string               // Alternative URL
          path?: string              // File path
          task_id?: string           // Generation task ID
          vendor?: string            // Video generation vendor
          subtitle_path?: string     // Subtitle file path
          // Image-specific fields (nano-banana-2 model)
          model_aspect_ratio?: string  // e.g. "9:16", "16:9"
          model_name?: string          // e.g. "banana_2"
          model_resolution?: string    // e.g. "1K", "2K"
          // Audio/TTS-specific fields
          format?: string              // e.g. "mp3"
          type?: string                // e.g. "audio"
          model_speech_count?: string  // Character count for TTS
        }
        posterUrl?: string           // Poster/thumbnail URL
        type?: string                // File MIME type
        referenceType?: number       // Reference type
      }
      text?: string                  // Associated text content
      extra?: Record<string, any>    // Additional metadata
      node?: {                       // Node/timeline information
        nodeID: string               // Unique node identifier
        xStart: number               // X position start
        yStart: number               // Y position start
        width: number                // Node width
        height: number               // Node height
        layer: number                // Layer index
        nodeType: number             // Node type identifier
        agentFile?: {                // Generated file details
          id: string                 // File ID
          name: string               // File name
          url: string                // File URL
          coverInfo?: {              // Cover image info
            coverURL: string         // Cover image URL
          }
          noWatermarkUrl?: string    // URL without watermark
          duration?: number          // Duration in seconds
          relativePath?: string      // Relative file path
          thumbnailUrl?: string      // Thumbnail URL
        }
        status: number               // Node status
        playWidth: number            // Playback width
        playHeight: number           // Playback height
        logoType: number             // Logo type identifier
      }
    }>
  }

  // Error information (only present when status is 'failed')
  error?: string | {                 // Error can be a string or object
    message: string                  // Error description
    status: number                   // HTTP status code
    details?: any                    // Additional error details
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/p123456789-u12345-a67890-bot:minimax"
```

**JavaScript**
``` javascript
const token = "YOUR_API_TOKEN";
const jobId = "p123456789-u12345-a67890-bot:minimax";
const apiUrl = `https://api.useapi.net/v1/minimax/agent/${jobId}`;

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const job = await response.json();
console.log('Job status:', job.status);

if (job.status === 'completed' && job.response?.attachments) {
  job.response.attachments.forEach(att => {
    console.log(`${att.file.fileName}: ${att.file.fileUrl}`);
  });
} else if (job.status === 'failed') {
  console.error('Job failed:', job.error);
}
```

**Python**
``` python
import requests

token = "YOUR_API_TOKEN"
job_id = "p123456789-u12345-a67890-bot:minimax"
api_url = f"https://api.useapi.net/v1/minimax/agent/{job_id}"

response = requests.get(
    api_url,
    headers={'Authorization': f'Bearer {token}'}
)

job = response.json()
print(f"Job status: {job['status']}")

if job['status'] == 'completed' and job.get('response', {}).get('attachments'):
    for att in job['response']['attachments']:
        print(f"{att['file']['fileName']}: {att['file']['fileUrl']}")
elif job['status'] == 'failed':
    print(f"Job failed: {job['error']}")
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs
## List Running Agent Jobs
<small>November 24, 2025</small>

---

List all currently running agent jobs for your account. This endpoint returns jobs that are still being processed (status: `started`).

Completed and failed jobs are not included in this list but can be retrieved using [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId) if you have the job ID.
> **https://api.useapi.net/v1/minimax/agent/jobs**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Responses

**200**
**200 OK**

List of running jobs returned successfully.

Returns jobs grouped by account with execution statistics.

```json
{
    "accounts": ["67890", "54321"],
    "summary": {
        "67890": {
            "executing": 2
        },
        "54321": {
            "executing": 1
        }
    },
    "executing": {
        "67890": [
            {
                "jobId": "p123456789-u12345-a67890-bot:minimax",
                "elapsed": "02:15"
            },
            {
                "jobId": "p987654321-u12345-a67890-bot:minimax",
                "elapsed": "01:30"
            }
        ],
        "54321": [
            {
                "jobId": "p456789123-u12345-a54321-bot:minimax",
                "elapsed": "00:45"
            }
        ]
    }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

##### Model

```typescript
{
  accounts: string[]                    // List of account IDs with configured access
  summary: Record<string, {
    executing: number                   // Number of currently executing jobs for this account
  }>
  executing: Record<string, Array<{     // Jobs grouped by account
    jobId: string                       // Job identifier
    elapsed: string                     // Elapsed time since job started (mm:ss format)
  }>>
}
```

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/jobs"
```

**JavaScript**
``` javascript
const token = "YOUR_API_TOKEN";
const apiUrl = "https://api.useapi.net/v1/minimax/agent/jobs";

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const result = await response.json();
console.log(`${result.accounts.length} account(s) configured`);

for (const account of result.accounts) {
  const summary = result.summary[account];
  if (summary) {
    console.log(`Account ${account}: ${summary.executing} job(s) executing`);
  }

  const jobs = result.executing[account] || [];
  jobs.forEach(job => {
    console.log(`  ${job.jobId} (${job.elapsed})`);
  });
}
```

**Python**
``` python
import requests

token = "YOUR_API_TOKEN"
api_url = "https://api.useapi.net/v1/minimax/agent/jobs"

response = requests.get(
    api_url,
    headers={'Authorization': f'Bearer {token}'}
)

result = response.json()
print(f"{len(result['accounts'])} account(s) configured")

for account in result['accounts']:
    summary = result['summary'].get(account)
    if summary:
        print(f"Account {account}: {summary['executing']} job(s) executing")

    jobs = result['executing'].get(account, [])
    for job in jobs:
        print(f"  {job['jobId']} ({job['elapsed']})")
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio-config ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio-config
## Retrieve audio configuration parameters
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/audio/config/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "t2a_emotion": [
        {
            "label": "Happy",
            "value": "happy"
        },
        {
            "label": "...",
            "value": "..."
        }
    ],
    "voice_tag_accent": [
        {
            "language": "English",
            "tag_name": "US (General)"
        },
        {
            "language": "...",
            "tag_name": "..."
        }
    ],
    "voice_tag_age": [
        {
            "tag_name": "Young Adult"
        },
        {
            "tag_name": "..."
        }
    ],
    "voice_tag_gender": [
        {
            "tag_name": "Male"
        },
        {
            "tag_name": "..."
        }
    ],
    "voice_tag_language": [
        {
            "tag_name": "English"
        },
        {
            "tag_name": "..."
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    t2a_emotion: {
        label: string
        value: string
    }[]
    voice_tag_accent: {
        language: string
        tag_name: string
    }[]
    voice_tag_age: {
        tag_name: string
    }[]
    voice_tag_gender: {
        tag_name: string
    }[]
    voice_tag_language: {
        tag_name: string
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/audio/config/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/config/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/config/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio-voices ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio-voices
## Retrieve the list of system and cloned audio voices
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Over **300** pre-built voices provided supporting the following:
* Languages: English, Chinese (Mandarin), Spanish, French, Russian, Portuguese, Indonesian, German, Japanese, Korean, Italian, Cantonese
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral
* Accents: US (General), English, Indian
* Ages: Young Adult, Adult, Middle-Aged, Senior
* Genders: Male, Female
> **https://api.useapi.net/v1/minimax/audio/voices/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `tag_list` is optional. Specify a comma-separated list of tags using those returned by [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config) to narrow down the returned results.    
  Example: `Italian,Female,Adult,Calm`
  
- `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`.   
  Default `page_size` is 500.  

- `is_system` is optional. Set to `false` if you want to retrieve a list of custom voices cloned via [POST audio/clone-voice](/docs/api-minimax-v1/post-minimax-audio-clone-voice). The entire list of custom voices will be returned at once, the `page` and `page_size` parameters will not be used.  
  Default is `true` (return system voices).  

##### Responses 

**200**
**200 OK**  

`GET` [https://api.useapi.net/v1/minimax/audio/voices/?tag_list=Italian,Female,Adult,Calm](https://api.useapi.net/v1/minimax/audio/voices/?tag_list=Italian,Female,Adult,Calm)

```json
{
    "voice_list": [
        {
            "voice_id": "209544421245048",
            "parent_voice_id": "0",
            "voice_name": "Diligent Leader",
            "tag_list": [
                "Italian",
                "Female",
                "Adult",
                "Calm",
                "Standard"
            ],
            "file_id": "",
            "cover_url": "https://cdn.hailuoai.video/moss/staging/2024-11-21-14/moss-audio/voice_cover//1732171514479796864-207331589841022.png?x-oss-process=image/resize,p_50/format,webp",
            "create_time": 1732711650948,
            "update_time": 1732711650948,
            "collected": false,
            "voice_status": 2,
            "sample_audio": "https://cdn.hailuoai.video/moss/staging/2024-11-25-20/moss-audio/voice_sample_audio/1732537441602153587-official_sample_audio/4_it05.mp3",
            "uniq_id": "Italian_DiligentLeader",
            "group_id": "0"
        }
    ],
    "total": 1,
    "has_more": false
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    voice_list: {
        voice_id: string
        parent_voice_id: string
        voice_name: string
        tag_list: string[]
        file_id: string
        cover_url: string
        create_time: number
        update_time: number
        collected: boolean
        voice_status: number
        sample_audio: string
        uniq_id: string
        group_id: string
        managed_by_api: boolean
        is_expired: boolean
        refresh_count: number
        cloned_id: string
        clone: {
            voice_name: string
            language_tag: string
            need_noise_reduction: boolean
            files: {
                file_id: string
                file_name: string
            }[]
        }
    }[]
    total: number
    has_more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/audio/voices/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/voices/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/voices/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio
## Retrieve the list of text-to-speech audio clips you have generated
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint will return audio clips generated by 

* [POST audio/create-mp3](/docs/api-minimax-v1/post-minimax-audio-create-mp3)
* [POST audio/create-stream](/docs/api-minimax-v1/post-minimax-audio-create-stream)
> **https://api.useapi.net/v1/minimax/audio/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`.   
  Default `page_size` is 100.  

##### Responses 

**200**
**200 OK**  

```json
{
    "audio_list": [
        {
            "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
            "audio_review": 0,
            "user_id": 987654321,
            "audio_title": "<Audio title>",
            "audio_url": "https://cdn.hailuoai.video/...mp3",
            "update_time": 1122334455778
        },
        {
            "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
            "audio_review": 0,
            "user_id": 987654321,
            "audio_title": "Audio title",
            "audio_url": "https://cdn.hailuoai.video/...mp3",
            "update_time": 1122334455779
        }
    ],
    "total": 2025,
    "has_more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    audio_list: {
        audio_id: string
        audio_review: number
        user_id: number
        audio_title: string
        audio_url: string
        update_time: number
    }[]
    total: number
    has_more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/audio/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio_audio_id ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio_audio_id
## Retrieve text-to-speech audio clip
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint will return audio clip generated by 

* [POST audio/create-mp3](/docs/api-minimax-v1/post-minimax-audio-create-mp3)
> **https://api.useapi.net/v1/minimax/audio/`audio_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify audio clip you want to retrieve.

##### Responses 

**200**
**200 OK**  

```json
{
    "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
    "audio_review": 0,
    "voice_info": {
        "voice_id": "209533299589184",
        "parent_voice_id": "0",
        "voice_name": "Calm Woman",
        "tag_list": [
            "English",
            "Female",
            "Adult",
            "Audiobook",
            "US (General)"
        ],
        "file_id": "",
        "cover_url": "https://cdn.hailuoai.video/...png",
        "create_time": 1122334455667,
        "update_time": 1122334455668,
        "collected": false,
        "voice_status": 2,
        "sample_audio": "https://cdn.hailuoai.video/...mp3",
        "uniq_id": "English_CalmWoman",
        "group_id": "0"
    },
    "text": "<Text>",
    "audio_url": "https://cdn.hailuoai.video/...mp3",
    "audio_title": "<Title>",
    "create_time": 1122334455667,
    "emotion": "Auto",
    "language_boost": "Auto",
    "speed": 1,
    "pitch": 0,
    "update_time": 0,
    "effects": {
        "deepen_lighten": 0,
        "stronger_softer": 0,
        "nasal_crisp": 0,
        "spacious_echo": true,
        "lofi_telephone": false,
        "robotic": false,
        "auditorium_echo": false
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
  audio_id: string
  audio_review: number
  voice_info: {
      voice_id: string
      parent_voice_id: string
      voice_name: string
      tag_list: string[]
      file_id: string
      cover_url: string
      create_time: number
      update_time: number
      collected: boolean
      voice_status: number
      sample_audio: string
      uniq_id: string
      group_id: string
  }
  text: string
  audio_url: string
  audio_title: string
  create_time: number
  emotion: string
  language_boost: string
  speed: number
  pitch: number
  update_time: number
  effects: {
      deepen_lighten: number
      stronger_softer: number
      nasal_crisp: number
      spacious_echo: boolean
      lofi_telephone: boolean
      robotic: boolean
      auditorium_echo: boolean
  }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/audio/audio_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const audio_id = "audio_id to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/${audio_id}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
audio_id = "audio_id to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/{audio_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features
## Retrieve your hailuoai.video and minimax.io/audio accounts information
<small>October 14, 2024 (May 31, 2025)</small>

---

Retrieve your [hailuoai.video](https://hailuoai.video) and [www.minimax.io/audio](https://www.minimax.io/audio) accounts information, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.   

This endpoint provides detailed information about available credits and features supported by your account, such as the list of models, credits required for different models, maximum size of jobs query, and so on.
> **https://api.useapi.net/v1/minimax/features/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "privilegeType": 0,
    "totalCredits": 100,
    "expireText": "100 points will expire within 24 hours",
    "videoCost": 30,
    "queueLength": 3,
    "memberText": "Subscribe",
    "memberHoverText": "",
    "expireTime": 0,
    "isNewUser": false,
    "questionText": "",
    "trialExpireTime": 0,
    "trialText": 0,
    "memberName": "Free",
    "newUserVersion": 0,
    "creditExpireText": [
        {
            "credit": 100,
            "endTime": 1748735999999
        }
    ],
    "modelControl": [
        {
            "modelId": "image-01",
            "videoCost": 1,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23000",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23010",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23001",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23011",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23102",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23021",
            "videoCost": 45,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        }
    ],
    "supportModes": [],
    "imageQueueLength": 5,
    "totalCreditsStr": "100",
    "isPaidSubscription": false,
    "canManagePlan": true,
    "audio": {
        "total_credit": 100,
        "sub_credits": [
            {
                "credit_type": 3,
                "end_time": 1748735999999,
                "credit": 100,
                "text": "",
                "record": [
                    {
                        "credit": 100,
                        "endTime": 1748735999999
                    }
                ],
                "coin_type": 0
            }
        ],
        "base_resp": {}
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    privilegeType: number
    totalCredits: number
    expireText: string
    videoCost: number
    queueLength: number
    memberText: string
    memberHoverText: string
    expireTime: number
    isNewUser: boolean
    questionText: string
    trialExpireTime: number
    trialText: number
    memberName: string
    newUserVersion: number
    creditExpireText: {
        credit: number
        endTime: number
    }[]
    modelControl: {
        modelId: string
        videoCost: number
        isMember: boolean
        freeCount: number
        durations: any[]
        resolutions: any[]
        modes: any[]
        videoCosts: any[]
    }[]
    supportModes: any[]
    imageQueueLength: number
    totalCreditsStr: string
    isPaidSubscription: boolean
    canManagePlan: boolean
    audio: {
        total_credit: number
        sub_credits: {
            credit_type: number
            end_time: number
            credit: number
            text: string
            record: {
                credit: number
                endTime: number
            }[]
            coin_type: number
        }[]
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/features/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/features/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/features/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files
## Retrieve the list of images you have uploaded
<small>October 14, 2024 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of uploaded images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint will return a list of all the images you've used previously to generate videos. Only images that were actually used for generation will be shown.

**NOTE**: As of March 2025, this endpoint appears to be retired both on [hailuoai.video](https://hailuoai.video) website and internally, as it is not used by any website API calls nor does it return any data. We decided to keep it just in case it is revived.
> **https://api.useapi.net/v1/minimax/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of files to return. Default 10.

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "file_id": "user:user_id-minimax:account-file:file_id_#1",
        "file_name": "<file name>",
        "file_type": "jpeg",
        "cdn_url": "<file ulr>",
        "oss_path": "<file path with name>",
        "file_scene": 10,
        "file_status": 1
    },
    {
        "file_id": "user:user_id-minimax:account-file:file_id_#n",
        "file_name": "<file name>",
        "file_type": "png",
        "cdn_url": "<file ulr>",
        "oss_path": "<file path with name>",
        "file_scene": 10,
        "file_status": 1
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  file_id: string
  file_name: string
  file_type: string
  cdn_url: string
  oss_path: string
  file_scene: number
  file_status: number
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/files/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId
## Retrieve image 
<small>March 17, 2025</small>

---

Use this endpoint to retrieve status and results of

* [POST images/create](/docs/api-minimax-v1/post-minimax-images-create)
> **https://api.useapi.net/v1/minimax/images/`imageId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
  "id": "<image_id>",
  "desc": "...prompt...",
  "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp",
  "videoURL": "https://cdn.hailuoai.video/....png",
  "status": 2,
  "canRetry": false,
  "width": 0,
  "height": 0,
  "originFiles": [],
  "canAppeal": false,
  "downloadURL": "https://cdn.hailuoai.video/....png",
  "hasVoice": false,
  "modelID": "image-01",
  "useOriginPrompt": false,
  "isBookmarked": false,
  "disableGenerateSimilar": false,
  "createTime": 1742173334234,
  "postStatus": 0,
  "userID": 923847293472394000,
  "createType": 4,
  "promptImgURL": "",
  "extra": {
    "cameraMotions": [],
    "promptStruct": ""
  },
  "isVisitor": false,
  "videoURLs": {
    "feedURL": "",
    "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png"
  },
  "priority": 0,
  "generatorType": 1,
  "isInFolder": false,
  "batchID": "357846312387492374",
  "aspectRatio": "9:16",
  "fileID": "user:<user>-minimax:<account>-file:<file_id>",
  "tags": [
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "image-01"
    },
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "Enable Optimization"
    },
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "Image to video"
    }
  ],
  "duration": 0,
  "resolution": 0,
  "humanCheckStatus": 0,
  "userIDStr": "<account>",
  "statusLabel": "completed",
  "statusFinal": true,
  "imageId": "user:<user>-minimax:<account>-image:<image_id>"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed 
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated

Optional fields `message` and `percent` will contain generation progress information.

```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    status: number
    message: string // Contains the message shown to the user while the image is being processed
    percent: number // Contains 0-100 percent while the image is being processed
    canRetry: boolean
    width: number
    height: number
    originFiles: any[]
    canAppeal: boolean
    downloadURL: string
    hasVoice: boolean
    modelID: string
    useOriginPrompt: boolean
    isBookmarked: boolean
    disableGenerateSimilar: boolean
    createTime: number
    postStatus: number
    userID: number
    createType: number
    promptImgURL: string
    extra: {
      cameraMotions: any[]
      promptStruct: string
    }
    isVisitor: boolean
    videoURLs: {
      feedURL: string
      downloadURLWithWatermark: string
    }
    priority: number
    generatorType: number
    isInFolder: boolean
    batchID: string
    aspectRatio: string
    fileID: string
    tags: {
      type: string
      tagIcon: string
      tagText: string
    }[]
    duration: number
    resolution: number
    humanCheckStatus: number
    userIDStr: string
    statusLabel: string
    statusFinal: boolean
    imageId: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/images/<imageId>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const imageId = "imageId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
imageId = "imageId to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images
## Retrieve the list of images you have generated
<small>March 17, 2025</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Returned image `fileID` value can be used as a parameter for [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).
> **https://api.useapi.net/v1/minimax/images/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of images to return. Default 30.

- `lastImageId` is optional, specify the image id from where to start.

##### Responses 

**200**
**200 OK**  

```json
{
    "images": [
        {
            "id": "<image_id>",
            "desc": "...prompt...",
            "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp",
            "videoURL": "https://cdn.hailuoai.video/....png",
            "status": 2,
            "canRetry": false,
            "width": 0,
            "height": 0,
            "originFiles": [],
            "canAppeal": false,
            "downloadURL": "https://cdn.hailuoai.video/....png",
            "hasVoice": false,
            "modelID": "image-01",
            "useOriginPrompt": false,
            "isBookmarked": false,
            "disableGenerateSimilar": false,
            "createTime": 1742173334234,
            "postStatus": 0,
            "userID": 923847293472394000,
            "createType": 4,
            "promptImgURL": "",
            "extra": {
                "cameraMotions": [],
                "promptStruct": ""
            },
            "isVisitor": false,
            "videoURLs": {
                "feedURL": "",
                "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png"
            },
            "priority": 0,
            "generatorType": 1,
            "isInFolder": false,
            "batchID": "357846312387492374",
            "aspectRatio": "9:16",
            "fileID": "user:<user>-minimax:<account>-file:<file_id>",
            "tags": [
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "image-01"
                },
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "Enable Optimization"
                },
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "Image to video"
                }
            ],
            "duration": 0,
            "resolution": 0,
            "humanCheckStatus": 0,
            "userIDStr": "<account>",
            "statusLabel": "completed",
            "statusFinal": true,
            "imageId": "user:<user>-minimax:<account>-image:<image_id>"
        }
    ],
    "hasPre": false,
    "hasNext": true,
    "processing": false,
    "total": 4135
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed  
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated
    
```typescript
{
  images: {
    id: string
    desc: string
    coverURL: string
    videoURL: string
    status: number
    canRetry: boolean
    width: number
    height: number
    originFiles: any[]
    canAppeal: boolean
    downloadURL: string
    hasVoice: boolean
    modelID: string
    useOriginPrompt: boolean
    isBookmarked: boolean
    disableGenerateSimilar: boolean
    createTime: number
    postStatus: number
    userID: number
    createType: number
    promptImgURL: string
    extra: {
      cameraMotions: any[]
      promptStruct: string
    }
    isVisitor: boolean
    videoURLs: {
      feedURL: string
      downloadURLWithWatermark: string
    }
    priority: number
    generatorType: number
    isInFolder: boolean
    batchID: string
    aspectRatio: string
    fileID: string
    tags: {
      type: string
      tagIcon: string
      tagText: string
    }[]
    duration: number
    resolution: number
    humanCheckStatus: number
    userIDStr: string
    statusLabel: string
    statusFinal: boolean
    imageId: string
  }[]
  hasPre: boolean
  hasNext: boolean
  processing: boolean
  total: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/images/?account=<account>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/images/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm-chatID ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm-chatID
## Retrieve the messages from the LLM chat
<small>March 7, 2025 (November 24, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax LLM has been decommissioned and will be replaced with upcoming Google AI and Gemini support.</b></span>

---

Equivalent of [chat.minimax.io](https://chat.minimax.io).

Use your [chat.minimax.io](https://chat.minimax.io) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/llm/`chatID`/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter

- `chatID` is **required**. Specify the chatID you want to retrieve.
  
##### Query Parameters

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "messages": [
        {
            "msgID": "1234567890",
            "createTime": 1741385047333,
            "content": "hola",
            "msgType": "user",
            "feadbackType": 0,
            "requestStatus": 0,
            "isEnd": 0,
            "chatID": "",
            "msgSubtype": 0,
            "chatStyle": "pro",
            "parentMsgID": "0",
            "otherAgentAnswer": {
                "botInfo": null
            },
            "failedText": "",
            "canEdit": true,
            "extra": {
                "parsedQuestion": [],
                "msgTitle": "",
                "links": [],
                "audioUrl": "",
                "chatBotList": [],
                "form": [],
                "copilotTable": [],
                "copilotHandled": false,
                "copilotTextLimit": 0,
                "netSearchStatus": {
                    "finalStatus": {
                        "status": "",
                        "statusCode": 0
                    },
                    "linkDetail": []
                },
                "feedbackStatus": {},
                "responseType": "",
                "followUpQuestions": [],
                "urlStatus": {},
                "generateImage": [],
                "replyMsgType": "",
                "generateProcess": "",
                "ciCallResults": [],
                "isUserStopped": false
            }
        },
        {
            "msgID": "1234567891",
            "createTime": 1741385047360,
            "content": "¡Hola! ¿Cómo estás hoy? Estoy aquí para ayudarte con cualquier cosa que necesites.",
            "msgType": "system",
            "feadbackType": 0,
            "requestStatus": 1,
            "isEnd": 0,
            "chatID": "",
            "msgSubtype": 0,
            "chatStyle": "pro",
            "parentMsgID": "9876543210",
            "otherAgentAnswer": {
                "botInfo": null
            },
            "failedText": "",
            "canEdit": false,
            "extra": {
                "parsedQuestion": [],
                "msgTitle": "",
                "links": [],
                "audioUrl": "",
                "chatBotList": [],
                "form": [],
                "copilotTable": [],
                "copilotHandled": false,
                "copilotTextLimit": 0,
                "netSearchStatus": {
                    "finalStatus": {
                        "status": "",
                        "statusCode": 0
                    },
                    "linkDetail": []
                },
                "feedbackStatus": {},
                "responseType": "",
                "followUpQuestions": [],
                "urlStatus": {},
                "generateImage": [],
                "replyMsgType": "",
                "generateProcess": "",
                "ciCallResults": [],
                "isUserStopped": false
            }
        }
    ],
    "title": "hola",
    "characterID": "1",
    "canSearch": true,
    "model": "mm-01"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    messages: {
        msgID: string
        createTime: number
        content: string
        msgType: string
        feadbackType: number
        requestStatus: number
        isEnd: number
        chatID: string
        msgSubtype: number
        chatStyle: string
        parentMsgID: string
        otherAgentAnswer: {
            botInfo: null
        }
        failedText: string
        canEdit: boolean
        extra: {
            parsedQuestion: any[]
            msgTitle: string
            links: any[]
            audioUrl: string
            chatBotList: any[]
            form: {
                formType: number
                content: string
                path: string
                fileID: string
                height: number
                width: number
                status: number
                fileByte: number
            }[]
            copilotTable: any[]
            copilotHandled: boolean
            copilotTextLimit: number
            netSearchStatus: {
                finalStatus: {
                    status: string
                    statusCode: number
                }
                linkDetail: any[]
            }
            feedbackStatus: { [key: string]: unknown }
            responseType: string
            followUpQuestions: any[]
            urlStatus: { [key: string]: unknown }
            generateImage: any[]
            replyMsgType: string
            generateProcess: string
            ciCallResults: any[]
            isUserStopped: boolean
        }
    }[]
    title: string
    characterID: string
    canSearch: boolean
    model: string
    statusInfo: {
        code: number
        httpCode: number
        message?: string
        messageEnglish?: string
        serviceTime: number
        requestID: string
        debugInfo: string
        serverAlert: number
    }
}   
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/llm/<chatID>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/minimax/llm/<chatID>`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/minimax/llm/<chatID>"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm
## Retrieve the list of LLM chats
<small>March 7, 2025 (November 24, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax LLM has been decommissioned and will be replaced with upcoming Google AI and Gemini support.</b></span>

---

Equivalent of [chat.minimax.io](https://chat.minimax.io).

Use your [chat.minimax.io](https://chat.minimax.io) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/llm/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of records to return. Default 20.

- `lastChatID` is optional, specify the chatID from where to start.

##### Responses 

**200**
**200 OK**  

```json
{
    "hasMore": true,
    "limit": 2,
    "items": [
        {
            "chatID": "123467890",
            "createTime": 1741385047356,
            "updateTime": 1741385047356,
            "chatTitle": "hola",
            "chatDescription": "hola",
            "requestStatus": 0,
            "isTop": false,
            "chatStyle": "pro",
            "robotID": 1,
            "robotName": "HiloAI",
            "robotAvatar": {
                "small": "https://cdn.yingshi-ai.com/….png",
                "medium": "https://cdn.yingshi-ai.com/….png",
                "large": "https://cdn.yingshi-ai.com/….png",
                "oversize": "https://cdn.yingshi-ai.com/….png"
            },
            "isPhoneMode": false,
            "type": 0,
            "attachments": [],
            "abstractContent": "¡Hola! ¿Cómo estás hoy? Estoy aquí para ayudarte con cualquier cosa que necesites.",
            "canSearch": true,
            "favoriteStatus": 0,
            "model": "mm-01"
        },
        {
            "chatID": "9876543210",
            "createTime": 1741385031166,
            "updateTime": 1741385031166,
            "chatTitle": "hola",
            "chatDescription": "hola",
            "requestStatus": 0,
            "isTop": false,
            "chatStyle": "pro",
            "robotID": 1,
            "robotName": "HiloAI",
            "robotAvatar": {
                "small": "https://cdn.yingshi-ai.com/….png",
                "medium": "https://cdn.yingshi-ai.com/….png",
                "large": "https://cdn.yingshi-ai.com/….png",
                "oversize": "https://cdn.yingshi-ai.com/….png"
            },
            "isPhoneMode": false,
            "type": 0,
            "attachments": [],
            "abstractContent": "<think>\nOkay, the user said \"hola\". That's Spanish for \"hello\". I should respond in Spanish to match their language.\n\nI need to make sure my response is friendly and welcoming. Maybe say \"¡Hola! ¿En qué puedo ayudarte hoy?\" which means \"Hello! How can I assist you today?\"\n\nWait, does the user need help with something specific? They might be testing if I understand Spanish. I'll keep it open-ended and ask how I can help them. That way they can proceed with their actual request.\n\nAlternatively, maybe they just want a greeting back. But it's better to prompt them to ask for assistance. So the response should be welcoming and encourage them to ask their question.\n</think>\n\n¡Hola! ¿En qué puedo ayudarte hoy?",
            "canSearch": true,
            "favoriteStatus": 0,
            "model": "mm-m1"
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    hasMore: boolean
    limit: number
    items: {
        chatID: string
        createTime: number
        updateTime: number
        chatTitle: string
        chatDescription: string
        requestStatus: number
        isTop: boolean
        chatStyle: string
        robotID: number
        robotName: string
        robotAvatar: {
            small: string
            medium: string
            large: string
            oversize: string
        }
        isPhoneMode: boolean
        type: number
        attachments: {
            id: string
            type: string
            fileID: string
            fileType: string
            fileName: string
            img: string
            link: string
            sceneId: string
            text: string
            title: string
            content: string
        }[]
        abstractContent: string
        canSearch: boolean
        favoriteStatus: number
        model: string
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/llm/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/llm/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/llm/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-create
## Compose music up to 60 seconds long using a text prompt
<small>September 25, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Equivalent of [hailuoai.com/music](https://hailuoai.com/music).  

Generate music in under 60 seconds. Add a new line to separate sentences. Add two empty lines for a pause.

Use [hailuoai.com/music](https://hailuoai.com/music) account to generate music, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/music/create?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `prompt` is **required**. Provide your lyrics.   
  Maximum length 600 characters.  

- `styleId` is **required**. Specify desired music [style](/docs/api-minimax-v1/get-minimax-music-styles).
  
- `title` is optional. 

##### Responses 

**200**

Use the returned `musicId` to retrieve full music results, such as `coverURL`, `style`, `lyrics` and moderation `status` by using [GET /music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId). 

Sometimes, MiniMax will apply post-moderation to an already generated song. In such cases, attempting to retrieve and play `audioURL` will fail, and the `status` of the generation will be set to `4`. Those songs will not appear under [GET /music](/docs/api-minimax-v1/get-minimax-music) and can only be retrieved by the [GET /music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId) endpoint.

```json
{
    "musicId": "user:1234-minimax:987654321-music:998877665544332211",
    "audioURL": "https://cdn.hailuoai.com/prod/2024-10-05-08/music/123456789-music_998877665544332211.mp3",
    "duration": 55,
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**422**
**422 Unprocessable Content**

Moderated prompt.

```json
{
    "error": "Moderated prompt"
}
```

**429**
**429 Too Many Requests**  

Only one concurrent music generation is supported per account.

```json
{
    "error": "The previous request has not been completed yet. Please try again later."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  musicId: string
  audioURL: string
  duration: number
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/music/create?styleId=…&prompt=…" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const styleId = "abcdef";      
const prompt = "lyrics";      
const apiUrl = `https://api.useapi.net/v1/minimax/music/create?styleId=${styleId}&prompt=${prompt}`; 
const token = "API token";
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
styleId = "abcdef";      
prompt = "lyrics";      
apiUrl = f"https://api.useapi.net/v1/minimax/music/create?styleId={styleId}&prompt={prompt}";  
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId
## Retrieve music 
<small>September 25, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Use this endpoint to retrieve status and results of

* [music/create](/docs/api-minimax-v1/get-minimax-music-create)
> **https://api.useapi.net/v1/minimax/music/`musicId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `musicId` is **required**. Specify the musicId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
  "title": "<title>",
  "lyrics": "<lyrics>",
  "style": "Popular",
  "coverURL": "https://minimax-public-cdn.com/music/final_v3/987654321.png",
  "audioURL": "https://cdn.hailuoai.com/prod/2024-10-05-08/music/987654321.mp3",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "createTime": 123456789,
  "duration": 38,
  "musicId": "user:user_id-minimax:account_id-music:music_id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **4** moderated

```typescript
{   // TypeScript, all fields are optional
    title: string
    lyrics: string
    style: string
    coverURL: string
    audioURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    createTime: number
    duration: number
    musicId: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/music/musicId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const musicId = "musicId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/music/${musicId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
musicId = "musicId to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/music/{musicId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-styles ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-styles
## Retrieve the list of music styles
<small>September 25, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

You can preview all styles at [music/create](/docs/api-minimax-v1/get-minimax-music-create#try-it)

Use [hailuoai.com/music](https://hailuoai.com/music) account to generate music, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/music/styles/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "name": "Classical",
        "styles": [
            {
                "url": "https://cdn.hailuoai.com/samle_1.mp3",
                "styleId": "<sample style id>",
                "name": "<sample ong name>"
            }
        ]
    },
    {
        "name": "World",
        "styles": [
            {
                "url": "https://cdn.hailuoai.com/samle_2.mp3",
                "styleId": "<sample style id>",
                "name": "<sample ong name>"
            },
            {
                "url": "https://cdn.hailuoai.com/samle_3.mp3",
                "styleId": "<sample style id>",
                "name": "<sample ong name>"
            }
        ]
    }    
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    name: string
    styles: {
        url: string
        styleId: string
        name: string
    }[]
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/music/styles/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/music/styles/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/music/styles/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music
## Retrieve the list of songs you have generated
<small>September 25, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Use [hailuoai.com/music](https://hailuoai.com/music) account to retrieve generated music, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/music/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of songs to return. Default 20.

- `lastMusicId` is optional, specify the music id from where to start.

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "title": "<title>",
        "lyrics": "<lyrics>",
        "style": "Urban",
        "coverURL": "https://minimax-public-cdn.com/music/final_v3/123456789.png",
        "audioURL": "https://cdn.hailuoai.com/prod/2024-10-05-08/music/123456789.mp3",
        "status": 2,
        "statusLabel": "completed",
        "statusFinal": true,
        "createTime": 123456789,
        "duration": 45,
        "musicId": "user:user_id-minimax:account_id-music:music_id"
    },
    {
        "title": "<title>",
        "lyrics": "<lyrics>",
        "style": "Popular",
        "coverURL": "https://minimax-public-cdn.com/music/final_v3/987654321.png",
        "audioURL": "https://cdn.hailuoai.com/prod/2024-10-05-08/music/987654321.mp3",
        "status": 2,
        "statusLabel": "completed",
        "statusFinal": true,
        "createTime": 123456789,
        "duration": 38,
        "musicId": "user:user_id-minimax:account_id-music:music_id"
    },
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **4** moderated

```typescript
{   // TypeScript, all fields are optional
    title: string
    lyrics: string
    style: string
    coverURL: string
    audioURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    createTime: number
    duration: number
    musicId: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/music/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/music/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/music/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available
## Retrieve the list of videos currently running via the API along with the available account capacity
<small>October 15, 2024 (March 17, 2025)</small>

---

This endpoint retrieves the list of images and videos currently running via the API along with the available account capacity.   

If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). 

If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). 

Please refer to code provided in article [Fun with MiniMax API](/docs/articles/minimax-bash) to see how this endpoint can be used in conjunction with [POST /files](/docs/api-minimax-v1/post-minimax-files) and [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).

**NOTE**: The available capacity (array `available`) includes only videos, the API does not include currently executing image generations in that capacity.
> **https://api.useapi.net/v1/minimax/scheduler/available**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
{
    "executing": [
        {
            "videoId": "user:user_id-minimax:account-video:id1",
            "started": "2024-09-25T01:55:16.128Z",
            "elapsed": "03:57",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        },
        {
            "videoId": "user:user_id-minimax:account-image:inN",
            "started": "2024-09-25T01:58:18.555Z",
            "elapsed": "00:35",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        }
    ],
    "available": [
        {
            "account": "<account_1>",
            "maxJobs": 5,
            "executing": 0,
            "available": 5
        },
        {
            "account": "<account_2>",
            "maxJobs": 5,
            "executing": 3,
            "available": 2
        },
        {
            "account": "<account_N>",
            "maxJobs": 3,
            "executing": 2,
            "available": 1
        }
    ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    executing: {
        videoId: string
        imageId: string
        started: string 
        elapsed: string 
        replyUrl: string
        replyRef: string
    }[]
    available: {
        account: string
        maxJobs: number
        executing: number
        available: number
    }[]
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/available`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/available"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler
## Retrieve the list of images and videos currently being executed by the API
<small>September 25, 2024 (March 17, 2025)</small>

---

This endpoint retrieves the list of images and videos currently being executed by the API.

If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). 

If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). 
> **https://api.useapi.net/v1/minimax/scheduler/**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
[
    {
        "videoId": "user:user_id-minimax:account-video:id1",
        "started": "2024-09-25T01:55:16.128Z",
        "elapsed": "03:57",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "videoId": "user:user_id-minimax:account-image:inN",
        "started": "2024-09-25T01:58:18.555Z",
        "elapsed": "00:35",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    videoId: string
    imageId: string
    started: number
    elapsed: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates
## Retrieve available agent video templates
<small>June 30, 2025</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve available agent video templates, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Templates can be used with [POST videos/agent-create](/docs/api-minimax-v1/post-minimax-videos-agent-create) to generate videos.
> **https://api.useapi.net/v1/minimax/videos/agent-templates/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `templateId` is optional, specify a template ID to get detailed information for a specific template including input requirements.

- `limit` is optional, specify the number of templates to return. Default 30.

- `lastId` is optional, specify the template id from where to start pagination.

##### Responses 

**200**
**200 OK**  

**Template List Response** (when `templateId` is not provided):

```json
{
    "videoList": [
        {
            "id": "1122334455667788",
            "createTime": 1702953600000,
            "videoAsset": {
                "id": "video_asset_id",
                "desc": "Template description",
                "coverURL": "https://example.com/cover.jpg",
                "videoURL": "https://example.com/video.mp4",
                "status": 2,
                "width": 1280,
                "height": 720,
                "duration": 10,
                "resolution": 1,
                "title": "Template Title",
                "agentTemplateID": "1122334455667788",
                "agentTemplateName": "Template Name",
                "downloadURL": "https://example.com/download.mp4",
                "hasVoice": true,
                "modelID": "model_123",
                "useOriginPrompt": false,
                "isBookmarked": false,
                "disableGenerateSimilar": false,
                "postStatus": 1,
                "userID": 123456,
                "createType": 1,
                "promptImgURL": "https://example.com/prompt.jpg",
                "aspectRatio": "16:9",
                "tags": [
                    {
                        "type": "style",
                        "tagIcon": "https://example.com/icon.png",
                        "tagText": "Cinematic"
                    }
                ],
                "humanCheckStatus": 1,
                "userIDStr": "123456"
            },
            "like": {
                "likes": 42,
                "likeStatus": 0
            },
            "author": {
                "userID": "user123",
                "name": "Author Name",
                "avatar": "https://example.com/avatar.jpg"
            },
            "cardType": 1,
            "tabID": "template"
        }
    ],
    "hasPre": false,
    "hasNext": true
}
```

**Template Details Response** (when `templateId` is provided):

```json
{
    "id": "1122334455667788",
    "createTime": 1702953600000,
    "videoAsset": {
        "id": "video_asset_id",
        "desc": "Template description",
        "coverURL": "https://example.com/cover.jpg",
        "videoURL": "https://example.com/video.mp4",
        "status": 2,
        "width": 1280,
        "height": 720,
        "duration": 10,
        "resolution": 1,
        "title": "Template Title",
        "agentTemplateID": "1122334455667788",
        "agentTemplateName": "Template Name"
    },
    "like": {
        "likes": 42,
        "likeStatus": 0
    },
    "author": {
        "userID": "user123",
        "name": "Author Name",
        "avatar": "https://example.com/avatar.jpg"
    },
    "cardType": 1,
    "tabID": "template",
    "credits": 100,
    "requirePrompt": true,
    "requireImage": true,
    "prompt": "Template prompt",
    "inputs": [
        {
            "name": "text_input",
            "type": "text",
        },
        {
            "name": "image_input", 
            "type": "image",
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```

##### Model 

```typescript
{   // TypeScript, template list response
    videoList: {
        id: string
        createTime: number
        videoAsset: {
            id: string
            desc: string
            coverURL: string
            videoURL: string
            status: number
            width: number
            height: number
            duration: number
            resolution: number
            title: string
            agentTemplateID: string
            agentTemplateName: string
            downloadURL?: string
            hasVoice?: boolean
            modelID?: string
            useOriginPrompt?: boolean
            isBookmarked?: boolean
            disableGenerateSimilar?: boolean
            postStatus?: number
            userID?: number
            createType?: number
            promptImgURL?: string
            aspectRatio?: string
            tags?: {
                type: string
                tagIcon: string
                tagText: string
            }[]
            humanCheckStatus?: number
            userIDStr?: string
        }
        like: {
            likes: number
            likeStatus: number
        }
        author: {
            userID: string
            name: string
            avatar: string
        }
        cardType: number
        tabID: string
    }[]
    hasPre: boolean
    hasNext: boolean
}

{   // TypeScript, template details response (when templateId provided)
    id: string
    createTime: number
    videoAsset: {} // Same structure as above
    like: {} // Same structure as above
    author: {} // Same structure as above
    cardType: number
    tabID: string
    credits: number
    requirePrompt: boolean
    requireImage: boolean
    prompt: string
    inputs: {
        name: string
        type: "text" | "image"
    }[]
}
```

##### Examples

**Curl**
``` bash
# Get list of templates
curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?account=account&limit=10" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 

# Get specific template details
curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=1122334455667788" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
// Get list of templates
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?account=${account}&limit=10`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("Templates:", {response, result});

// Get specific template details
const templateId = "1122334455667788";
const detailUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=${templateId}`;
const detailResponse = await fetch(detailUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const templateDetails = await detailResponse.json();
console.log("Template details:", {detailResponse, templateDetails});
```

**Python**
``` python
import requests

# Get list of templates
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?account={account}&limit=10"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print("Templates:", response, response.json())

# Get specific template details
template_id = "1122334455667788"
detail_url = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId={template_id}"
detail_response = requests.get(detail_url, headers=headers)
print("Template details:", detail_response, detail_response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters
## Retrieve the list of characters
<small>January 9, 2025 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint returns a list of previously created characters, the same list you see when navigating to Subject Reference » Add Reference Character » My Characters.
> **https://api.useapi.net/v1/minimax/videos/characters/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `page` is optional, specify the page number. Default 1.

- `pageSize` is optional, specify number of items to return. Default 50.

##### Responses 

**200**
**200 OK**  

Field `cdnUrl` contains a link to the originally uploaded file.  
Field `promptImgUrl` contains a link to the detected character face from the file mentioned above.

```json
[
    {
        "characterID": "1234567890",
        "characterType": 1,
        "file": {
            "fileID": "user:user_id-minimax:account-file:file_id",
            "cdnUrl": "https://cdn.hailuoai.video/...jpeg",
            "promptImgUrl": "https://cdn.hailuoai.video/..."
        }
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    characterID: string
    characterType: number
    file: {
        fileID: string
        cdnUrl: string
        promptImgUrl: string
    }
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/characters/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/characters/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/characters/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId
## Retrieve video 
<small>September 25, 2024</small>

---

Use this endpoint to retrieve status and results of

* [videos/create](/docs/api-minimax-v1/post-minimax-videos-create)
> **https://api.useapi.net/v1/minimax/videos/`videoId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
  "id": "id",
  "desc": "<prompt>",
  "coverURL": "<cover url>",
  "videoURL": "<generated video with watermark url>",
  "downloadURL": "<generated video without watermark (paid accounts) url>",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "percent": 100,
  "width": 1300,
  "height": 760,
  "originFiles": [
    {
      "id": "user:user_id-minimax:account-file:file_id",
      "url": "<file url>",
      "type": "png"
    }
  ],
  "canAppeal": false,
  "canRetry": false,
  "videoId": "user:user_id-minimax:account-video:id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

This most often means that the video was moderated and removed after it was generated.

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed 
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated

Optional fields `message` and `percent` will contain generation progress information.
  
```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    downloadURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    message: string // Contains the message shown to the user while the video is being processed
    percent: number // Contains 0-100 percent while the video is being processed
    width: number
    height: number
    originFiles: {
      id: string
      url: string
      type: string
    }[]
    canAppeal: boolean    
    canRetry: boolean
    videoId: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/videoId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const videoId = "videoId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
videoId = "videoId to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos
## Retrieve the list of videos you have generated
<small>September 25, 2024 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/videos/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of videos to return. Default 30.

- `lastVideoId` is optional, specify the video id from where to start.

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "id": "video_id_#1",
        "desc": "",
        "coverURL": "",
        "videoURL": "",
        "status": 1,
        "statusLabel": "processing",
        "statusFinal": false,
        "message": "<Message from chairman Xi>",
        "width": 0,
        "height": 0,
        "originFiles": [],
        "canAppeal": false,
        "canRetry": false,
        "videoId": "user:user_id-minimax:account-video:video_id_#1"
    },
    {
        "id": "video_id_#2",
        "desc": "<prompt>",
        "coverURL": "<cover url>",
        "videoURL": "<generated video with watermark url>",
        "downloadURL": "<generated video without watermark (paid accounts) url>",
        "status": 2,
        "statusLabel": "completed",
        "statusFinal": true,
        "width": 1300,
        "height": 760,
        "originFiles": [
            {
                "id": "user:user_id-minimax:account-file:file_id",
                "url": "<file url>",
                "type": "png"
            }
        ],
        "canAppeal": false,
        "canRetry": false,
        "videoId": "user:user_id-minimax:account-video:video_id_#2"
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed  
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated
    
```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    downloadURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    message: string,
    width: number
    height: number
    originFiles: {
      id: string
      url: string
      type: string
    }[]
    canAppeal: boolean
    canRetry: boolean
    videoId: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account
## Create or update MiniMax API account configuration
<small>September 25, 2024 (March 17, 2025)</small>

---

See [Setup MiniMax](/docs/start-here/setup-minimax) for details.     

For your convenience, you can specify your MiniMax configuration values under your account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax.
> **https://api.useapi.net/v1/minimax/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "url": "MiniMax url",
    "token": "MiniMax token",
    "maxJobs": 1-10,
}
```
- `url` and `token` are **required**. Please see [Setup MiniMax](/docs/start-here/setup-minimax) for details. 

- `maxJobs` is **required**. Currently, it should be between 1 and 10.   
  For **video** accounts, please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue.  

##### Responses 

**201**
**201 Created** 

```json
{
    "account": "123456",
    "jwt": {
        "token": "abc…secured…xyz",
        "user": {
            "deviceID": "123456789",
            "id": "123456",
            "isAnonymous": true,
            "name": "<name>",
            "avatar": "<url>"
        },
        "exp": 1734858598.864,
        "iat": 1732266598.864,
        "host": "hailuoai.video",
        "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
        "iat_Issued": "2024-01-01T00:00:00.000Z",
        "exp_Expire": "2024-12-01T00:00:00.000Z"
    },
    "maxJobs": 1,
    "supportVideo": true,
    "supportChat": true,
    "supportAudio": true
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  account: string
  jwt: {
    token: string
    user: {
      deviceID: string
      id: string
      isAnonymous: boolean
      name: string
      avatar: string
    },
    exp: number
    iat: number
    host: string
    searchParams: string
    iat_Issued: string
    exp_Expire: string
  }
  maxJobs: number
  supportMusic: boolean
  supportVideo: boolean
  supportAudio: boolean
  supportChat: boolean
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/accounts \
     -d '{"url": "…", "token": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const url = "MiniMax url";      
const token = "MiniMax token";      
const apiUrl = `https://api.useapi.net/v1/minimax/accounts`; 
const api_token = "API token";
const maxJobs = 1;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  url, token, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
url = "MiniMax url"
token = "MiniMax token"
apiUrl = f"https://api.useapi.net/v1/minimax/accounts" 
api_token = "API token"
maxJobs = 1
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "url": f"{url}", 
    "token": f"{token}", 
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent
## Execute AI Agent with Multi-Model Support
<small>November 24, 2025 (February 24, 2026)</small>

---

Execute MiniMax AI Agent with support for multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02), [Veo 3.1](https://deepmind.google/models/veo/) including S2V subject reference, [Sora 2](https://openai.com/sora/)), image generation ([Midjourney V7/NiJi 7](https://www.midjourney.com/), [Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)).

The agent API can operate in synchronous or asynchronous mode.

Be very specific in your prompt about the type of content you want to generate. Explicitly state "generate a video", "generate an image", or "generate a song based on my lyrics" to ensure the agent uses the correct model from your provided list. You can also specify aspect ratio and resolution directly in your prompt, e.g., "create 1:1 4K image of a sunset" or "generate 16:9 video of waves". Without clear instructions, the agent may choose a different model or generate unexpected content type (e.g., generating a video when you wanted an image). To verify which model was actually used along with the resolution and aspect ratio, check the `file.extra` fields in the response (see [Model](#model) section for `model_name`, `model_aspect_ratio`, `model_resolution` fields).

This endpoint features dynamic capacity limits. If you receive a `429` response, wait for at least one job to complete (or wait ~30 seconds) and try again. Use [GET agent/jobs](/docs/api-minimax-v1/get-minimax-agent-jobs) to monitor running jobs.

Execution Times:
- Simple one-step tasks: 20-60 seconds
- Medium complexity tasks: 60 seconds to 2 minutes
- Multi-step complex tasks with multiple models: 5+ minutes
- Jobs expire after 15 minutes

Use [hailuoai.video](https://hailuoai.video) account to execute agent tasks, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

 **Note:**  
 Model `nano-banana-2` Nano Banana 2/Pro has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people. Use responsibly and in compliance with applicable laws and regulations.
> **https://api.useapi.net/v1/minimax/agent**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body

Below is a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) `multipart/form-data` example using Postman notation:

| Key       | Type | Value (example)                   |
| --------- | ---- | --------------------------------- |
| account   | Text | Optional MiniMax API account      |
| prompt    | Text | Generate a video of a cat playing |
| models    | Text | hailuo-2.3,nano-banana-2          |
| file      | File | «Reference.jpg»                   |
| file      | File | «Style.png»                       |
| async     | Text | false                             |
| replyUrl  | Text | https://webhook.site/your-id      |
| replyRef  | Text | my-task-123                       |

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required**, describe your request to the AI agent.

- `models` is **required**, comma-separated list of AI models to use.
  Supported models:

  **Video Models - Hailuo:**
  - `hailuo-2.3` - Hailuo 2.3 (highest quality)
  - `hailuo-2.3-fast` - Hailuo 2.3-Fast (faster generation)
  - `hailuo-02` - Hailuo 02

  **Video Models - Veo & Sora:**
  - `veo-3.1` - Veo 3.1 (Google DeepMind)
  - `veo-3.1-fast` - Veo 3.1 Fast
  - `veo-3.1-s2v` - Veo 3.1 S2V (subject reference)
  - `veo-3.1-s2v-fast` - Veo 3.1 S2V Fast
  - `sora-2` - Sora 2 (OpenAI)

  **Image Models - MiniMax:**
  - `nano-banana-2` - Nano Banana 2/Pro
  - `nano-banana` - Nano Banana
  - `seedream` - Seedream 4.5

  **Image Models - Third Party:**
  - `midjourney-v7` - Midjourney V7
  - `midjourney-niji7` - Midjourney NiJi 7
  - `seedream-5.0` - Seedream 5.0 (ByteDance)
  - `kontext` - Kontext (Flux)
  - `qwen` - Qwen Image (Alibaba)
  - `kolors` - Kolors (Kuaishou)

  **Audio Models - TTS:**
  - `speech-2.5-hd-preview` - Speech 2.5 HD Preview
  - `speech-2.5-turbo-preview` - Speech 2.5 Turbo Preview

  **Audio Models - Music:**
  - `minimax-music-2.0` - MiniMax Music 2.0

  Example: `"hailuo-2.3,nano-banana-2"` will use both Hailuo 2.3 video and Nano Banana 2/Pro image models.

- `file` is optional, attach reference files for the agent to process. You can upload multiple files.

- `async` is optional. When set to `true`, the API returns immediately with a job ID and processes the request in the background. Default: `false` (synchronous).

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once the agent task is completed or failed.
  The callback payload format matches the response [Model](/docs/api-minimax-v1/get-minimax-agent-jobId#model) shown below.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this agent response/result.
  Maximum length 1024 characters.

##### Responses

**200**
**200 OK**

Agent task completed successfully (synchronous mode).

```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "completed",
    "created": "2025-11-24T12:34:56.789Z",
    "request": {
        "account": "67890",
        "prompt": "Generate a video of a cat playing piano",
        "models": [
            "hailuo-2.3",
            "nano-banana-2"
        ],
        "replyUrl": "https://webhook.site/your-webhook-id",
        "replyRef": "my-task-123"
    },
    "response": {
        "projectID": "123456789",
        "sectionID": "987654321",
        "chatID": "456789123",
        "msg_content": "I've generated a video of a cat playing piano and an image variation.",
        "timestamp": 1732366496789,
        "elapsedTime": "02:15",
        "attachments": [
            {
                "attachmentID": "att_123456789",
                "type": 1,
                "status": 3,
                "file": {
                    "fileName": "cat_piano_video.mp4",
                    "fileUrl": "https://cdn.hailuoai.video/...mp4",
                    "type": "video/mp4",
                    "extra": {
                        "width": "1280",
                        "height": "720",
                        "duration": "5.0",
                        "fps": "24",
                        "no_watermark_url": "https://cdn.hailuoai.video/.../no_watermark.mp4",
                        "watermark_url": "https://cdn.hailuoai.video/.../watermark.mp4",
                        "thumbnail_url": "https://cdn.hailuoai.video/.../thumb.jpg"
                    }
                }
            },
            {
                "attachmentID": "att_987654321",
                "type": 2,
                "status": 3,
                "file": {
                    "fileName": "cat_piano_image.png",
                    "fileUrl": "https://cdn.hailuoai.video/...png",
                    "type": "image/png",
                    "extra": {
                        "model_name": "banana_2",
                        "model_aspect_ratio": "16:9",
                        "model_resolution": "1K"
                    }
                }
            }
        ]
    }
}
```

**201**
**201 Created**

Agent task created and processing in background (asynchronous mode with `async: true`).

Use the returned `jobId` to check status via [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId).

```json
{
    "jobId": "p987654321-u12345-a67890-bot:minimax",
    "status": "started",
    "created": "2025-11-24T12:30:00.000Z",
    "request": {
        "account": "67890",
        "prompt": "Generate a video of a cat playing piano",
        "models": [
            "hailuo-2.3"
        ],
        "async": true,
        "replyUrl": "https://webhook.site/your-webhook-id",
        "replyRef": "my-task-456"
    },
    "response": {
        "projectID": "987654321",
        "sectionID": "123456789",
        "chatID": "456789012"
    }
}
```

**400**
**400 Bad Request**

Invalid request parameters.

```json
{
  "error": "Error …",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**422**
**422 Unprocessable Content**

Moderated content or invalid file.

```json
{
  "error": "Your prompt contains content that violates our policies"
}
```

**429**
**429 Too Many Requests**

Dynamic capacity limit reached. Wait for at least one job to complete (or wait ~30 seconds) and try again.

```json
{
  "error": "Agent generation failed"
}
```

**500**
**500 Internal Server Error**

Agent execution failed.

```json
{
  "jobId": "p123456789-u12345-a67890-bot:minimax",
  "status": "failed",
  "created": "2025-11-23T12:34:56.789Z",
  "request": {
    "prompt": "Generate a video",
    "models": ["hailuo-2.3"]
  },
  "error": {
    "message": "Agent connection error",
    "status": 500
  }
}
```

**504**
**504 Gateway Timeout**

Agent task timed out after 15 minutes.

```json
{
  "jobId": "p123456789-u12345-a67890-bot:minimax",
  "status": "failed",
  "created": "2025-11-23T12:34:56.789Z",
  "request": {
    "prompt": "Generate a video",
    "models": ["hailuo-2.3"]
  },
  "error": {
    "message": "Timeout waiting for assistant response",
    "status": 504
  }
}
```

**596**
**596 Pending mod message**

Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### Model

- `response.attachments[].file.fileUrl` - primary download URL (may have watermark)
- `response.attachments[].file.extra.no_watermark_url` - URL without watermark (when available)
- `response.attachments[].file.extra.watermark_url` - URL with watermark
- `response.attachments[].node.agentFile.noWatermarkUrl` - alternative watermark-free URL
- `response.attachments[].node.agentFile.url` - alternative file URL

```typescript
{
  // Job metadata
  jobId: string                      // Unique job identifier
  status: 'started' | 'completed' | 'failed'  // Job status
  created: string                    // ISO 8601 timestamp
  code?: number                      // HTTP status code (optional)

  // Original request
  request: {
    prompt: string                   // User's prompt
    file?: Array<{                   // File metadata (actual files not included)
      name: string
      size: number
      type: string
    }>
    models: string[]                 // Model IDs used
    async?: boolean                  // Async mode flag
    replyUrl?: string               // Callback URL
    replyRef?: string               // User's reference ID
  }

  // Agent response (only present on completion)
  response?: {
    projectID: string                // MiniMax project ID
    sectionID: string                // MiniMax section ID
    chatID: string                   // MiniMax chat ID
    msg_content: string              // Agent's response message
    timestamp: number                // Response timestamp (milliseconds since epoch)
    elapsedTime: string              // Elapsed time (mm:ss format)
    attachments?: Array<{            // Generated files
      attachmentID: string           // Attachment identifier
      type: number                   // Attachment type (numeric)
      status: number                 // Attachment status (3 = completed)
      file: {
        fileName: string             // File name
        fileUrl: string              // CDN URL to download file
        extra?: {                    // Additional file metadata
          // Video-specific fields
          height?: string            // Video height in pixels
          width?: string             // Video width in pixels
          duration?: string          // Duration in seconds
          fps?: string               // Frames per second
          frames?: string            // Total frame count
          no_watermark_url?: string  // CDN URL without watermark
          watermark_url?: string     // CDN URL with watermark
          thumbnail_url?: string     // Thumbnail image URL
          url?: string               // Alternative URL
          path?: string              // File path
          task_id?: string           // Generation task ID
          vendor?: string            // Video generation vendor
          subtitle_path?: string     // Subtitle file path
          // Image-specific fields (nano-banana-2 model)
          model_aspect_ratio?: string  // e.g. "9:16", "16:9"
          model_name?: string          // e.g. "banana_2"
          model_resolution?: string    // e.g. "1K", "2K"
          // Audio/TTS-specific fields
          format?: string              // e.g. "mp3"
          type?: string                // e.g. "audio"
          model_speech_count?: string  // Character count for TTS
        }
        posterUrl?: string           // Poster/thumbnail URL
        type?: string                // File MIME type
        referenceType?: number       // Reference type
      }
      text?: string                  // Associated text content
      extra?: Record<string, any>    // Additional metadata
      node?: {                       // Node/timeline information
        nodeID: string               // Unique node identifier
        xStart: number               // X position start
        yStart: number               // Y position start
        width: number                // Node width
        height: number               // Node height
        layer: number                // Layer index
        nodeType: number             // Node type identifier
        agentFile?: {                // Generated file details
          id: string                 // File ID
          name: string               // File name
          url: string                // File URL
          coverInfo?: {              // Cover image info
            coverURL: string         // Cover image URL
          }
          noWatermarkUrl?: string    // URL without watermark
          duration?: number          // Duration in seconds
          relativePath?: string      // Relative file path
          thumbnailUrl?: string      // Thumbnail URL
        }
        status: number               // Node status
        playWidth: number            // Playback width
        playHeight: number           // Playback height
        logoType: number             // Logo type identifier
      }
    }>
  }

  // Error information (only present on failure)
  error?: string | {                 // Error can be a string or object
    message: string                  // Error description
    status: number                   // HTTP status code
    details?: any                    // Additional error details
  }
}
```

##### Examples

**Curl**
``` bash
# Synchronous request
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "prompt=Generate a video of a cat playing piano" \
     -F "models=hailuo-2.3,nano-banana-2" \
     "https://api.useapi.net/v1/minimax/agent"

# Asynchronous request
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "prompt=Generate a video of a cat playing piano" \
     -F "models=hailuo-2.3" \
     -F "async=true" \
     -F "replyUrl=https://webhook.site/your-webhook-id" \
     "https://api.useapi.net/v1/minimax/agent"

# With file upload
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "prompt=Generate a video using this reference" \
     -F "models=hailuo-2.3" \
     -F "file=@/path/to/reference.jpg" \
     "https://api.useapi.net/v1/minimax/agent"
```

**JavaScript**
``` javascript
const token = "YOUR_API_TOKEN";
const apiUrl = "https://api.useapi.net/v1/minimax/agent";

// Synchronous request
const formData = new FormData();
formData.append('prompt', 'Generate a video of a cat playing piano');
formData.append('models', 'hailuo-2.3,nano-banana-2');

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const result = await response.json();
console.log("Job completed:", result);

if (result.response?.attachments) {
  result.response.attachments.forEach(att => {
    console.log(`${att.file.fileName}: ${att.file.fileUrl}`);
  });
}

// Asynchronous request
const asyncFormData = new FormData();
asyncFormData.append('prompt', 'Generate a video of a cat playing piano');
asyncFormData.append('models', 'hailuo-2.3');
asyncFormData.append('async', 'true');
asyncFormData.append('replyUrl', 'https://webhook.site/your-webhook-id');

const asyncResponse = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: asyncFormData
});

const asyncResult = await asyncResponse.json();
console.log("Job ID:", asyncResult.jobId);
```

**Python**
``` python
import requests

token = "YOUR_API_TOKEN"
api_url = "https://api.useapi.net/v1/minimax/agent"

headers = {
    "Authorization": f"Bearer {token}"
}

# Synchronous request
data = {
    "prompt": "Generate a video of a cat playing piano",
    "models": "hailuo-2.3,nano-banana-2"
}

response = requests.post(api_url, headers=headers, data=data)
result = response.json()
print("Job completed:", result)

if result.get('response', {}).get('attachments'):
    for att in result['response']['attachments']:
        print(f"{att['file']['fileName']}: {att['file']['fileUrl']}")

# Asynchronous request
async_data = {
    "prompt": "Generate a video of a cat playing piano",
    "models": "hailuo-2.3",
    "async": "true",
    "replyUrl": "https://webhook.site/your-webhook-id"
}

async_response = requests.post(api_url, headers=headers, data=async_data)
async_result = async_response.json()
print("Job ID:", async_result['jobId'])
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-clone-voice ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-clone-voice
## Clone a voice using uploaded audio samples
## Table of contents
<small>December 27, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>
---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Make sure that you have slots are available for cloned voices. To check, please navigate to [https://www.minimax.io/audio/voices](https://www.minimax.io/audio/voices) and select "My Voices" as shown below. Single [www.minimax.io/audio](https://www.minimax.io/audio) account can have up to 4 cloned voices, if you need more simple create another [www.minimax.io/audio](https://www.minimax.io/audio) account.

Please be patient, voice cloning can take up to 60 seconds. This endpoint can only support one or two parallel tasks maximum, so organize internal queuing if you need to clone many voices in bulk.
> **https://api.useapi.net/v1/minimax/audio/clone-voice**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "files": "user:user_id-minimax:account-file:file_id1,user:user_id-minimax:account-file:file_id2",
    "voice_name": "Doctor Who",
    "language_tag": "English",
}
```
- `voice_name` is **required**.   
  Maximum length: 30 characters.

- `language_tag` is **required**. Use tag_name from array `voice_tag_language` of [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config). 

- `files` is **required**. Provide up to 10 comma-separated `fileID` values of audio samples uploaded via [POST audio/upload-sample](/docs/api-minimax-v1/post-minimax-audio-upload-sample). Each audio sample should be between 10 to 60 seconds long. 

- `need_noise_reduction` is optional.   
  Supported values: `true` (default), `false`.  

##### Responses 

**200**
**200 OK** 

```json
{
    "voice_id": "user:user_id-minimax:account_id-audio:voice_id",
    "parent_voice_id": "0",
    "voice_name": "Doctor Who",
    "tag_list": [
        "English"
    ],
    "file_id": "1234567890",
    "cover_url": "https://cdn.hailuoai.video/...png",
    "create_time": 1122334455667,
    "update_time": 1122334455667,
    "collected": false,
    "voice_status": 2,
    "sample_audio": "https://cdn.hailuoai.video/...mp3",
    "uniq_id": "<uniq_id>",
    "group_id": "<group_id>"
}
```

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    voice_id: string
    parent_voice_id: string
    voice_name: string
    tag_list: string[]
    file_id: string
    cover_url: string
    create_time: number 
    update_time: number 
    collected: boolean
    voice_status: number
    sample_audio: string
    uniq_id: string
    group_id: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/audio/clone-voice \
     -d '{"voice_name": "…", "language_tag": "…", "files": …}'
```

**JavaScript**
``` javascript
const voice_name = "Voice Name";      
const language_tag = "Voice Language";      
const files = "fileID1,fileID2";      
const apiUrl = `https://api.useapi.net/v1/minimax/audio/clone-voice`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  voice_name, language_tag, files
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
voice_name = "Voice Name"
language_tag = "Voice Language"
files = "fileID1,fileID2" 
apiUrl = f"https://api.useapi.net/v1/minimax/audio/clone-voice" 
api_token = "API token"
maxJobs = 1
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "voice_name": f"{voice_name}", 
    "language_tag": f"{language_tag}", 
    "files": files
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-create-mp3 ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-create-mp3
## Create text-to-speech audio 
## Table of contents
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>
---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint creates an mp3 audio from the provided text in under 10 seconds. 
* Up to **20** parallel jobs per account are supported. 

Over **300** pre-built voices provided [GET audio/voices](/docs/api-minimax-v1/get-minimax-audio-voices) supporting the following:
* Languages:  English (US, UK, Australia, India), Chinese (Mandarin and Cantonese), Japanese, Korean, French, German, Spanish, Portuguese (including Brazilian), Italian, Arabic, Russian, Turkish, Dutch, Ukrainian, Vietnamese, and Indonesian.  
  The list is constantly updated to include more languages!
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral
* Accents: US (General), English, Indian
* Ages: Young Adult, Adult, Middle-Aged, Senior
* Genders: Male, Female
> **https://api.useapi.net/v1/minimax/audio/create-mp3**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax www.minimax.io/audio API account",
    "text": "Required text",
    "voice_id": "Required voice id"
}
```
- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `text` is **required**. Insert `<#0.5#>` to add a 0.5s pause between sentences. Adjust the duration as needed.   
  Maximum length: 500 characters / 30 seconds.   
  **NOTE** You can generate mp3 for text tens times longer using combination of [POST audio/create-stream](/docs/api-minimax-v1/post-minimax-audio-create-stream) and [WSS audio/wss](/docs/api-minimax-v1/wss-minimax-audio-wss).  

- `voice_id` is **required**. Use [GET audio/voices](/docs/api-minimax-v1/get-minimax-audio-voices) to get list of all available voices.  

- `model` is optional.  
  Supported values: `speech-02-hd` (default), `speech-01-hd`, `speech-02-turbo`, `speech-01-turbo`.

- `language_boost` is optional. Use tag_name from array `voice_tag_language` of [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `emotion` is optional. Use value from array `t2a_emotion` of [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `vol` is optional.  
  Default 1.

- `speed` is optional.  
  Valid range: 0.5…2, default 1.

- `pitch` is optional.  
  Valid range: -12…12, default 0.

- `deepen_lighten` is optional.  
  Valid range: -100…100, default 0.

- `stronger_softer` is optional.  
  Valid range: -100…100, default 0.

- `nasal_crisp` is optional.  
  Valid range: -100…100, default 0.

- `spacious_echo` is optional.   
  Supported values: `true`, `false` (default).  

- `lofi_telephone` is optional.   
  Supported values: `true`, `false` (default).  
   
- `robotic` is optional.   
  Supported values: `true`, `false` (default).  

- `auditorium_echo` is optional.   
  Supported values: `true`, `false` (default).  

##### Responses 

**200**
**200 OK** 

Use returned `audio_url` to download generated mp3 audio file.   
Use returned `audio_id` to retrieve full details using [GET audio/`audio_id`](/docs/api-minimax-v1/get-minimax-audio_audio_id).

```json
{
    "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
    "audio_length": 0,
    "audio_sample_rate": 32000,
    "audio_size": 1234567,
    "bitrate": 128000,
    "word_count": 0,
    "invisible_character_ratio": 0,
    "usage_characters": 500,
    "audio_format": "mp3",
    "audio_channel": 1,
    "input_sensitive": false,
    "trace_id": "<trace id>",
    "chunks": 5123,
    "audio_review": 0,
    "user_id": 11223344556677,
    "audio_title": "<autogenerated title>",
    "audio_url": "https://cdn.hailuoai.video/...mp3",
    "update_time": 123456789
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    audio_id: string
    audio_length: number
    audio_sample_rate: number
    audio_size: number
    bitrate: number
    word_count: number
    invisible_character_ratio: number
    usage_characters: number
    audio_format: string
    audio_channel: number
    input_sensitive: boolean
    trace_id: string
    chunks: number
    audio_review: number
    user_id: number
    audio_title: string
    audio_url: string
    update_time: number
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/audio/create-mp3" \
     -d '{"text": "…", "voice_id": "…"}'
```

**JavaScript**
``` javascript
const text = "text";      
const voice_id = "voice_id";      
const apiUrl = `https://api.useapi.net/v1/minimax/audio/create-mp3`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  text, voice_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
text = "text"
voice_id = "voice_id"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/create-mp3" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "text": f"{text}",
    "voice_id": f"{voice_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-create-stream ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-create-stream
## Create text-to-speech audio stream token and payload
## Table of contents
<small>December 23, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>
---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint creates a near real-time audio stream from the provided text. 
* Average time to response is **3** seconds. 
* Up to **20** parallel jobs per account are supported.

Over **300** pre-built voices provided [GET audio/voices](/docs/api-minimax-v1/get-minimax-audio-voices) supporting the following:
* Languages:  English (US, UK, Australia, India), Chinese (Mandarin and Cantonese), Japanese, Korean, French, German, Spanish, Portuguese (including Brazilian), Italian, Arabic, Russian, Turkish, Dutch, Ukrainian, Vietnamese, and Indonesian.  
  The list is constantly updated to include more languages!
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral
* Accents: US (General), English, Indian
* Ages: Young Adult, Adult, Middle-Aged, Senior
* Genders: Male, Female

Returned by this endpoint `token` and `payload` will be used by WebSocket [WSS audio/wss](/docs/api-minimax-v1/wss-minimax-audio-wss).
> **https://api.useapi.net/v1/minimax/audio/create-stream**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax www.minimax.io/audio API account",
    "text": "Required text",
    "voice_id": "Required voice id"
}
```
- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `text` is **required**. Insert `<#0.5#>` to add a 0.5s pause between sentences. Adjust the duration as needed.  
  Maximum length: 5000 characters.

- `voice_id` is **required**. Use [GET audio/voices](/docs/api-minimax-v1/get-minimax-audio-voices) to get list of all available voices.  

- `model` is optional.  
  Supported values: `speech-02-hd` (default), `speech-01-hd`, `speech-02-turbo`, `speech-01-turbo`.

- `language_boost` is optional. Use tag_name from array `voice_tag_language` of [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `emotion` is optional. Use value from array `t2a_emotion` of [GET audio/config](/docs/api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `vol` is optional.  
  Default 1.

- `speed` is optional.  
  Valid range: 0.5…2, default 1.

- `pitch` is optional.  
  Valid range: -12…12, default 0.

- `deepen_lighten` is optional.  
  Valid range: -100…100, default 0.

- `stronger_softer` is optional.  
  Valid range: -100…100, default 0.

- `nasal_crisp` is optional.  
  Valid range: -100…100, default 0.

- `spacious_echo` is optional.   
  Supported values: `true`, `false` (default).  

- `lofi_telephone` is optional.   
  Supported values: `true`, `false` (default).  
   
- `robotic` is optional.   
  Supported values: `true`, `false` (default).  

- `auditorium_echo` is optional.   
  Supported values: `true`, `false` (default).  

##### Responses 

**200**
**200 OK** 

Field `token` and `payload` values are used by WebSocket [WSS audio/wss](/docs/api-minimax-v1/wss-minimax-audio-wss).
- The `token` contains WebSocket authorization information and will expire in 24 hours.
- The `payload` contains a properly formed and validated payload built from user-provided input. You should send this payload over the WebSocket to generate a real-time sound stream and optionally retrieve the generated MP3 file.

```typescript
{
    "token": "token for WSS WebSocket endpoint",
    "payload": {
        "msg_id": "1e53d-a593-e40b9-54e20-f29c84-40ae3",
        "payload": {
            "model": "",
            "text": "Text for TTS generation",
            "voice_setting": {
                "speed": 1,
                "vol": 1,
                "pitch": 0,
                "voice_id": "123456789",
                "emotion": "happy"
            },
            "audio_setting": {},
            "effects": {
                "deepen_lighten": 0,
                "stronger_softer": 0,
                "nasal_crisp": 0,
                "spacious_echo": false,
                "lofi_telephone": false,
                "robotic": false,
                "auditorium_echo": false
            },
            "er_weights": [],
            "language_boost": "German",
            "stream": true
        }
    }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

##### Examples

The code provided at [WSS audio/wss](/docs/api-minimax-v1/wss-minimax-audio-wss#examples) is used on this page when you use the [Try It](#try-it) feature.

##### Model 

Field `token` and `payload` values are used by WebSocket [WSS audio/wss](/docs/api-minimax-v1/wss-minimax-audio-wss).
- The `token` contains WebSocket authorization information and will expire in 24 hours.
- The `payload` contains a properly formed and validated payload built from user-provided input. You should send this payload over the WebSocket to generate a real-time sound stream and optionally retrieve the generated MP3 file.

```typescript
{ // TypeScript, all fields are optional
  token: string
  payload: {}
}
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-delete-voice ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-delete-voice
## Delete cloned voice
<small>December 27, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint deletes a voice cloned via [POST audio/clone-voice](/docs/api-minimax-v1/post-minimax-audio-clone-voice).  

This endpoint will return a response `200` if you're trying to delete a cloned voice that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/accounts/`account`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax account",
    "voice_id": "1234567890",
}
```

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `voice_id` is **required**, use value of field voice_id returned by [POST audio/clone-voice](/docs/api-minimax-v1/post-minimax-audio-clone-voice) or [GET audio/voices/?is_system=false](/docs/api-minimax-v1/get-minimax-audio-voices) 

##### Responses 

**200**
**200 OK** 

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/audio/delete-voice \
     -d '{"account": "…", "voice_id": "…"}'
```

**JavaScript**
``` javascript
const account = "MiniMax account";      
const voice_id = "voice id";      
const apiUrl = `https://api.useapi.net/v1/minimax/audio/delete-voice`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "MiniMax account"
voice_id = "voice id"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/delete-voice" 
api_token = "API token"
maxJobs = 1
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "voice_id": f"{voice_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-upload-sample ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-audio-upload-sample
## Upload audio samples for voice cloning  
<small>December 27, 2024 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Upload `.mp3` and `.wav` audio samples that you want to use for your voice cloning via [POST audio/clone-voice](/docs/api-minimax-v1/post-minimax-audio-clone-voice). Each audio sample should be between 10 to 60 seconds long.  

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/minimax/audio/upload-sample/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type | File Extension |
| ------------ | -------------- |
| audio/mpeg   | mp3            |
| audio/wav    | wav            |
| audio/wave   | wav            |

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  ossPath: string
  fileID: string
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/audio/upload-sample/?account=account" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary /path/to/your/voice-sample.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured audio account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/audio/upload-sample/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const audioUrl = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3";
    const responseAudio = await fetch(audioUrl);
    blob = await responseAudio.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const audioFileName = "./voice-sample.mp3";
    blob = new Blob([await fsp.readFile(audioFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="audio-file" type="file"> 
    const audioFile = document.getElementById(`audio-file`);
    if (audioFile.files[0])
        blob = audioFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured audio account"
apiUrl = f"https://api.useapi.net/v1/minimax/audio/upload-sample/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# audio_url = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3"
# response_audio = requests.get(audio_url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
# audio_file_path = "./voice-sample.mp3"
# with open(audio_file_path, 'rb') as audio_file:
#     file_content = audio_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files
## Upload image, audio, or video file
<small>October 15, 2024 (May 4, 2026)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to upload image, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Upload media (images, audio, video) up to 5GB in size that you want to use as references in [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) or [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

Supported formats:
- **Images** (`.png`, `.jpeg`, `.webp`) — first frame, end frame, character/subject reference, omni image reference. `.webp` uploads via `Content-Type: image/jpeg`.
- **Audio** (`.mp3`, `.wav`) — Seedance omni audio references (`audioFileID1`…`audioFileID3`, resolved as `@Audio1`…`@Audio3`).
- **Video** (`.mp4`) — Seedance omni video references (`videoFileID1`…`videoFileID3`, resolved as `@Video1`…`@Video3`).

Please **be patient**, on average, it takes about 1 minute per GB to upload.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/minimax/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type | File Extension | Used for |
| ------------ | -------------- | -------- |
| image/png    | png            | Image references (all video/image models) |
| image/jpeg   | jpeg           | Image references; also `.webp` (uploaded as jpeg) |
| audio/mpeg   | mp3            | Seedance omni audio reference (`audioFileID*`) |
| audio/wav    | wav            | Seedance omni audio reference (`audioFileID*`) |
| video/mp4    | mp4            | Seedance omni video reference (`videoFileID*`) |

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  ossPath: string
  fileID: string
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/files/?account=account" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: image/jpeg" \
  --data-binary /path/to/your/image.jpeg
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured video account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch image from URL
    const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
    const responseImage = await fetch(imageUrl);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load image from local file (Blob)
    const fsp = require('fs').promises;
    const imageFileName = "./cat.png";
    blob = new Blob([await fsp.readFile(imageFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="image-file" type="file"> 
    const imageFile = document.getElementById(`image-file`);
    if (imageFile.files[0])
        blob = imageFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured video account"
apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# file_content = response_image.content

# # Example 2: Load image from local file
# image_file_path = "./image.jpg"
# with open(image_file_path, 'rb') as image_file:
#     file_content = image_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create
## Create an image using a text prompt
## Table of contents
<small>March 17, 2025 (May 13, 2026)</small>
---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

##### Model Comparison Matrix

| Model | Resolutions | Aspect Ratios | Ref Images | @-mention |
|:------|:------------|:--------------|:-----------|:---------:|
| image-01 | HD | 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9 | 1 via `characterFileId` | — |
| nano-banana-2 | 512P, 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| nano-banana-pro | 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| gpt-image-1.5 | Low, Medium, High | auto (default), 1:1, 3:2, 2:3 | 1-3 via `referenceFileId1`…`3` | — |
| gpt-image-2 | 1K, 2K, 4K | 16:9 (default), 21:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-16 via `referenceFileId1`…`16` | ✓ |
| seedream-4.5 | 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| seedream-5.0 | 2K, 3K | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | ✓ |
| midjourney-v7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — |
| midjourney-niji7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — |

Models with **@-mention** support let you reference uploaded images by slot inside the `prompt` (e.g. `"@Image1 with bokeh background"`). The token is `@Image<N>` where `<N>` is the slot from `referenceFileId<N>`. Case-insensitive: `@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`. Unsupported models reject prompts containing `@Image<N>` tokens.

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Credits are charged per image. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing.

| Model | Resolution | Credits per image | Quantity |
|:------|:-----------|:-----------------:|:---------|
| image-01 | HD | 1 | 1-4 |
| nano-banana-2 | 512P, 1K | 4 | 1-4 |
| nano-banana-2 | 2K | 5 | 1-4 |
| nano-banana-2 | 4K | 8 | 1-4 |
| nano-banana-pro | 1K, 2K | 6 | 1-4 |
| nano-banana-pro | 4K | 10 | 1-4 |
| gpt-image-1.5 | Low | 4 | 1-4 |
| gpt-image-1.5 | Medium | 8 | 1-4 |
| gpt-image-1.5 | High | 15 | 1-4 |
| gpt-image-2 (quality `low`) | 1K | 2 | 1-4 |
| gpt-image-2 (quality `low`) | 2K | 5 | 1-4 |
| gpt-image-2 (quality `low`) | 4K | 10 | 1-4 |
| gpt-image-2 (quality `medium`) | 1K | 8 | 1-4 |
| gpt-image-2 (quality `medium`) | 2K | 20 | 1-4 |
| gpt-image-2 (quality `medium`) | 4K | 40 | 1-4 |
| gpt-image-2 (quality `high`) | 1K | 30 | 1-4 |
| gpt-image-2 (quality `high`) | 2K | 80 | 1-4 |
| gpt-image-2 (quality `high`) | 4K | 160 | 1-4 |
| seedream-4.5 | 2K, 4K | 4 | 1-4 |
| seedream-5.0 | 2K, 3K | 4 | 1-4 |
| midjourney-v7 | n/a | 3 | 4 (fixed) |
| midjourney-niji7 | n/a | 3 | 4 (fixed) |

</details>

To retrieve generated image(s), use:
* [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId)
* [GET images](/docs/api-minimax-v1/get-minimax-images)
> **https://api.useapi.net/v1/minimax/images/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax API account",
    "prompt": "Required text prompt",
    "promptOptimization": true,
    "model": "nano-banana-pro",
    "aspectRatio": "16:9",
    "resolution": "2K",
    "referenceFileId1": "user:…-minimax:…-file:…",
    "referenceFileId2": "user:…-minimax:…-file:…",
    "quantity": 2,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```

##### Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required**, describe your image.
  Maximum length depends on model: 1,250 characters for `image-01`, `gpt-image-1.5`, `gpt-image-2`, `seedream-4.5`; 5,000 characters for `nano-banana-2`, `nano-banana-pro`, `seedream-5.0`, `midjourney-v7`, `midjourney-niji7`.

  **@-mention syntax** (supported by `gpt-image-2`, `nano-banana-pro`, `nano-banana-2`, `seedream-4.5`, `seedream-5.0`): use `@Image1`…`@Image16` in the prompt to reference uploaded images by slot — `@Image1` binds to `referenceFileId1`, `@Image2` to `referenceFileId2`, etc. Tokens are case-insensitive (`@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`). Models without @-mention support (`image-01`, `gpt-image-1.5`, `midjourney-v7`, `midjourney-niji7`) reject prompts containing `@Image<N>` tokens with a 400.

- `promptOptimization` is optional.
  Supported values: `true` (default), `false`.

- `model` is optional.
  Supported values:
  * `image-01` (default) - Character-focused image generation with HD resolution. Supports character reference via `characterFileId`.
  * `nano-banana-2` - Image generation (512P/1K/2K/4K) with up to 14 reference images. Lower cost flash variant.
  * `nano-banana-pro` - High-resolution image generation (1K/2K/4K) with up to 14 reference images.
  * `gpt-image-1.5` - High-resolution image generation (Low/Medium/High) with up to 3 reference images and limited aspect ratios.
  * `gpt-image-2` - GPT Image 2 (1K/2K/4K, `quality` = low/medium/high) with 10 aspect ratios and up to 16 reference images via `referenceFileId1`…`16` (with @-mention support).
  * `seedream-4.5` - High-resolution image generation (2K/4K) with up to 14 reference images.
  * `seedream-5.0` - High-resolution image generation (2K/3K) with up to 14 reference images.
  * `midjourney-v7` - Midjourney V7 image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images.
  * `midjourney-niji7` - Midjourney NiJi 7 anime-focused image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images.

- `resolution` is optional, model-specific.
  * `image-01`: Only `HD` supported (default).
  * `nano-banana-2`: `512P` (default), `1K`, `2K`, `4K`.
  * `nano-banana-pro`: `1K` (default), `2K`, `4K`.
  * `gpt-image-1.5`: `Low` (default), `Medium`, `High`.
  * `gpt-image-2`: `1K` (default), `2K`, `4K`.
  * `seedream-4.5`: `2K` (default), `4K`.
  * `seedream-5.0`: `2K` (default), `3K`.
  * `midjourney-v7`: Not applicable (no resolution parameter).
  * `midjourney-niji7`: Not applicable (no resolution parameter).

- `aspectRatio` is optional, model-specific.
  * `image-01`: `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`, `21:9`.
  * `nano-banana-2`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `nano-banana-pro`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `gpt-image-1.5`: `auto` (default), `1:1`, `3:2`, `2:3`.
  * `gpt-image-2`: `16:9` (default), `21:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. (No `auto` — model doesn't accept it.)
  * `seedream-4.5`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `seedream-5.0`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.
  * `midjourney-v7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.
  * `midjourney-niji7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.

- `quality` is optional, **only for `gpt-image-2`**.
  Supported values: `low` (default), `medium`, `high`. Credit cost varies by quality × resolution — see the credits estimator above. Other models reject the `quality` parameter with a 400.

- `characterFileId` is optional, **only for `image-01`**:
    * fileID of the character image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files). Upload a clear front-facing photo for best result. Avoid side angles and obstructions.
    * Cannot be used with other models (use `referenceFileId1`…`16` instead).

- `referenceFileId1` … `referenceFileId16` are optional, **for all models except `image-01`**:
    * fileID(s) of reference images uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files).
    * `gpt-image-2`: Supports 1-16 reference images (`referenceFileId1`…`16`). Supports @-mention syntax in prompt.
    * `nano-banana-2`, `nano-banana-pro`, `seedream-4.5`, `seedream-5.0`: Supports 1-14 reference images. Supports @-mention syntax in prompt.
    * `midjourney-v7`, `midjourney-niji7`: Supports 1-14 reference images. Does **not** support @-mention syntax — `@ImageN` tokens in prompt return 400.
    * `gpt-image-1.5`: Supports 1-3 reference images (`referenceFileId1`…`3` only). Does **not** support @-mention syntax.
    * `image-01`: Use `characterFileId` instead.
    * Slots must be **contiguous starting at 1** — sending `referenceFileId3` without `referenceFileId1`/`2` returns 400.
    * All reference files must belong to the same account.

- `quantity` is optional. Supported range: 1…4, default 1.
  **Note:** `midjourney-v7` and `midjourney-niji7` always generate exactly 4 images per request. The `quantity` parameter is ignored for these models.

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax image completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax image response/result.
  Maximum length 1024 characters.  

##### Responses 

**200**
**200 OK** 

Use returned in array `imageIds` values to retrieve image status and results using [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated image with the `status` **2** (Completed).

If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-images-create#request-body) the API will call the provided `replyUrl` with image progress updates until the image is complete or fails.

```json
{
    "id": "<image_id_1>",
    "task": {
        "batchID": "<batch_id>",
        "videoIDs": [
            "<image_id_1>",
            "<image_id_2>",
            "<image_id_3>",
            "<image_id_4>"
        ]
    },
    "isFirstGenerate": false,
    "imageIds": [
        "user:<user>-minimax:<account>-image:<image_id_1>",
        "user:<user>-minimax:<account>-image:<image_id_2>",
        "user:<user>-minimax:<account>-image:<image_id_3>",
        "user:<user>-minimax:<account>-image:<image_id_4>"
    ],
    "replyUrl": "https://webhook.site/…",
    "replyRef": "2025-03-11T17:23:05.795Z",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. Please recharge to get more credits or try again next day.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

```json
{
    "error": "There are currently multiple tasks in the queue, and only <number> can be generated at once"
}
```

**596**
**596 Pending mod message** 

Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked.  Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  id: string
  task: {
    batchID: string
    videoIDs: string[]
  }
  isFirstGenerate: boolean
  imageIds: string[]
  replyUrl: string
  replyRef: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/images/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/images/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/images/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-llm
## Chat with LLM
## Table of contents
<small>March 7, 2025 (November 24, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax LLM has been decommissioned and will be replaced with upcoming Google AI and Gemini support.</b></span>
---

Equivalent of [chat.minimax.io](https://chat.minimax.io).

Use your [chat.minimax.io](https://chat.minimax.io) account for this endpoint, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Up to **five** parallel requests are supported per individual [chat.minimax.io](https://chat.minimax.io) account. If you need more parallel executions, please add additional [chat.minimax.io](https://chat.minimax.io) accounts.  

Please visit 🚀 [Chat with AI](/assets/llm_chat/) to try a fully-fledged chat demo that features the entire LLM functionality available via our API, complete with full source code.

Feel free to chat with our 🤖 [Ask AI](/assets/aibot/) support bot, which is powered by this very API.

Currently following  models supported:

| Model                                                       | Context Length                   | Notes                            |
| ------------------------------------------------------------| -------------------------------- | -------------------------------- |
| [MiniMax-M1](https://github.com/MiniMax-AI/MiniMax-M1)      | 1M-token input, 80k-token output | Reasoning model                  |
| [MiniMax-Text-01](https://github.com/MiniMax-AI/MiniMax-01) | 1M-token input                   | Fast model with concise response |

Both models support file uploads for processing and are capable of executing real-time web searches.
> **https://api.useapi.net/v1/minimax/llm**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body 

Below is a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) `multipart/form-data` example using Postman notation:

| Key       | Type | Value (example)              |
| --------- | ---- | ---------------------------- |
| account   | Text | Optional MiniMax API account |
| prompt    | Text | Required text prompt         |
| model     | Text | mm-m1                        |
| searchWeb | Text | true                         |
| stream    | Text | true                         |
| chatID    | Text | 123456789                    |
| file      | File | «Notes.txt»                  |
| file      | File | «Design.doc»                 |
| file      | File | «ProjectPlan.jpeg»           |
| file      | File | «Invoice.pdf»                |

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `prompt` is **required**.   
  Note: We strongly advise that you sanitize your prompts and remove all URLs. Currently, it appears that the AI will attempt to fetch every URL it finds in the request body, and this will ultimately lead to a failure. You can observe similar behavior when posting the same request at [chat.minimax.io](https://chat.minimax.io).

- `model` is optional.  
  Supported values:  
  *  `mm-m1` [MiniMax-M1](https://github.com/MiniMax-AI/MiniMax-M1) (default)
  *  `mm-01` [MiniMax-Text-01](https://github.com/MiniMax-AI/MiniMax-01)   
  
- `searchWeb` is optional, set it to `true` if you want the LLM to perform real-time web searches for your request. The default value is `false`.   
  This can *significantly* slow down LLM response time.

- `chatID` is optional, if you want to continue a conversation thread, include the `chatID` from a previous response to retain the full conversation context within the same chat thread.  

- `stream` is optional, set it to `true` if you want a real-time `Content-Type: text/event-stream` response. The default value is `false`, which returns a `Content-Type: application/json` response.   
  We **strongly** recommend using the streaming approach when working with MiniMax-M1 or when sending complex queries in general to avoid timeouts.
  
- `file` is optional, provide up to 10 files with the following extensions: txt, docx, doc, pdf, ppt, pptx, xls, xlsx, png, jpeg, jpg, webp, svg, heif, tiff. The maximum file size is 100MB.   
Consider adding one file at a time to ensure each file is accepted. You may include a simple prompt (e.g., "here's my file x of y") along with the file if you're not ready to process it immediately and need to add all the files. All your files will be retained within the chat `chatID` context.   
Note that you can *repeat* the `file` parameter with different values multiple times, this is supported by [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData).

##### Responses 

**200**
**200 OK** 

For the responses below, we used a simple request with the prompt `tell me a joke` and the model `mm-01`.

A. `stream` parameter set to `true`, response `Content-Type: text/event-stream`:
   
  ```bash
  event:send_result
  data:{"type":1,"data":{"sendResult":{"userMsgID":"829104756293847156","chatID":"460283175649302817","systemMsgID":"167982430562198437","msgContent":"tell me a joke","wordSpreadRate":11,"chatTitle":"tell me a joke","canSearch":false,"canEdit":true,"extra":{"longCutCopyWriting":""},"isPreSendResult":false}},"statusInfo":{"code":0,"message":"Success"}}

  event:message_result
  data:{"type":2,"data":{"messageResult":{"msgID":"167982430562198437","chatID":"460283175649302817","msgType":"system","content":"Sure, here's a light-hearted joke","requestStatus":6,"isEnd":1,"msgSubType":0,"parentMsgID":"829104756293847156","extra":{"netSearchStatus":{"finalStatus":{"statusCode":0}},"warningText":""},"canRetry":false}},"statusInfo":{"code":0,"message":"success"}}

  event:message_result
  data:{"type":2,"data":{"messageResult":{"msgID":"167982430562198437","chatID":"460283175649302817","msgType":"system","content":"Sure, here's a light-hearted joke for you:\n\nWhy don't scientists trust atoms?\n\nBecause they make up everything!\n\nI hope that","requestStatus":6,"isEnd":1,"msgSubType":0,"parentMsgID":"829104756293847156","extra":{"netSearchStatus":{"finalStatus":{"statusCode":0}},"warningText":""},"canRetry":false}},"statusInfo":{"code":0,"message":"success"}}

  event:message_result
  data:{"type":2,"data":{"messageResult":{"msgID":"167982430562198437","chatID":"460283175649302817","msgType":"system","content":"Sure, here's a light-hearted joke for you:\n\nWhy don't scientists trust atoms?\n\nBecause they make up everything!\n\nI hope that brought a smile to your face! If you have any other requests or topics you'd like to","requestStatus":6,"isEnd":1,"msgSubType":0,"parentMsgID":"829104756293847156","extra":{"netSearchStatus":{"finalStatus":{"statusCode":0}},"warningText":""},"canRetry":false}},"statusInfo":{"code":0,"message":"success"}}

  event:message_result
  data:{"type":2,"data":{"messageResult":{"msgID":"167982430562198437","chatID":"460283175649302817","msgType":"system","content":"Sure, here's a light-hearted joke for you:\n\nWhy don't scientists trust atoms?\n\nBecause they make up everything!\n\nI hope that brought a smile to your face! If you have any other requests or topics you'd like to discuss, feel free to let me know.","requestStatus":1,"isEnd":0,"msgSubType":0,"parentMsgID":"829104756293847156","extra":{"netSearchStatus":{"finalStatus":{"statusCode":0}},"feedbackStatus":{},"replyMsgType":"text","warningText":""},"canRetry":true}},"statusInfo":{"code":0,"message":"success"}}

  event:close_chunk
  data:{"type":8}

  ```

B. `stream` parameter set to `false` (default), response `Content-Type: application/json`:  
   
  ```json
  {
    "request": {
      "sendResult": {
        "userMsgID": "930471528374615029",
        "chatID": "471639820571230486",
        "systemMsgID": "628940173205471392",
        "msgContent": "tell me a joke",
        "wordSpreadRate": 11,
        "chatTitle": "tell me a joke",
        "canSearch": false,
        "canEdit": true,
        "extra": {
          "longCutCopyWriting": ""
        },
        "isPreSendResult": false
      }
    },
    "response": {
      "messageResult": {
        "msgID": "628940173205471392",
        "chatID": "471639820571230486",
        "msgType": "system",
        "content": "Sure, here's a light-hearted joke for you:\n\nWhy don't scientists trust atoms?\n\nBecause they make up everything!\n\nI hope that brought a smile to your face! If you have any other requests or topics you'd like to discuss, feel free to let me know.",
        "requestStatus": 1,
        "isEnd": 0,
        "msgSubType": 0,
        "parentMsgID": "930471528374615029",
        "extra": {
          "netSearchStatus": {
            "finalStatus": {
              "statusCode": 0
            }
          },
          "feedbackStatus": {},
          "replyMsgType": "text",
          "warningText": ""
        },
        "canRetry": true
      }
    }
  }
  ```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**422**
**422 Unprocessable Content**

LLM is refusing to process your file(s) likely due to content moderation. This applies when the `stream` parameter is set to `false`, response `Content-Type` of `application/json`.

```json
{
  "error": "Invalid file. Please try another one"
}
```

**429**
**429 Too Many Requests**  

You have reached the maximum number of allowed parallel executions. Please wait until the running ones are completed and try again.

```json
{
    "error": "The previous request has not been completed yet. Please try again later."
}
```

##### Model `Content-Type: text/event-stream`

See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format.

```bash
event:<even name>
data:<See SSE model>

event:<even name>
data:<See SSE model>

…
```

###### SSE model
```typescript
{ // TypeScript, all fields are optional
  type: number
  data: {
    messageResult: {
      msgID: string
      chatID: string
      msgType: string
      content: string
      requestStatus: number
      isEnd: number
      msgSubType: number
      parentMsgID: string
      extra: {
        netSearchStatus: {
          finalStatus: {
            statusCode: number
          }
        }
        warningText: string
      }
      canRetry: boolean
    }
  }
  statusInfo: {
    code: number
    message: string
  }
}
```

###### SSE parser

When parsing the SSE response, we look for the very last occurrence of `event:message_result` where `data.type` is `2`. If any of the values in `data.statusInfo.code` are non-zero, it indicates that an error has occurred.

<details markdown="block">

<summary>Expand <code class="language-plaintext highlighter-rouge"><b>SSE parser code (JavaScript):</b></code></summary>

```javascript
  /**
   * Generic SSE stream parser function.
   * It reads the response stream chunk by chunk, decodes text,
   * and reconstructs complete SSE events. When an event is complete,
   * it calls the provided onEvent callback with the event name and event data.
   *
   * @param {Response} response - Fetch API Response object with a body stream.
   * @param {Function} onEvent - Callback receiving (eventName, eventData) when an SSE event is complete.
   */
  async function parseSSEStream(response, onEvent) {
    const reader = response.body.getReader();
    const decoder = new TextDecoder("utf-8");
    let buffer = "";
    let currentEvent = { event: null, data: "" };

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      const chunk = decoder.decode(value, { stream: true });
      buffer += chunk;
      const lines = buffer.split(/\r?\n/);
      // Preserve the last (possibly incomplete) line in the buffer.
      buffer = lines.pop();
      for (const line of lines) {
        if (line.trim() === "") {
          // Blank line indicates the end of an event.
          if (currentEvent.event && currentEvent.data) {
            onEvent(currentEvent.event, currentEvent.data);
          }
          currentEvent = { event: null, data: "" };
        } else {
          if (line.startsWith("event:")) {
            currentEvent.event = line.slice("event:".length).trim();
          } else if (line.startsWith("data:")) {
            // Append data for events that span multiple lines.
            currentEvent.data += line.slice("data:".length).trim();
          }
        }
      }
    }

    // Process any remaining event data in the buffer.
    if (currentEvent.event && currentEvent.data) {
      onEvent(currentEvent.event, currentEvent.data);
    }

    await reader.closed;
  }

  /**
   * Process an SSE stream from a POST request.
   * This function sends a request to the provided URL with the given payload,
   * then uses the generic SSE parser to process events.
   *
   * The provided eventHandler callback is invoked for each processed event.
   *
   * @param {string} url - The API endpoint URL.
   * @param {object} payload - The JSON payload to be sent in the POST body.
   * @param {Function} eventHandler - Callback receiving (eventName, parsedEventData).
   * @returns {Promise<Headers>} - Resolves with the response headers (in case extra metadata is needed).
   */
  async function processSSE(url, payload, eventHandler) {
    try {
      const response = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload)
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP error! status: ${response.status}\n${errorText}`);
      }

      // Define how to process each SSE event.
      await parseSSEStream(response, (eventName, eventDataStr) => {
        try {
          // Parse the event data as JSON.
          const eventData = JSON.parse(eventDataStr);

          // If the event data contains a statusInfo with a non-zero code, treat it as an error.
          if (eventData.statusInfo && eventData.statusInfo.code !== 0) {
            eventHandler("error", { code: eventData.statusInfo.code, message: eventData.statusInfo.message });
            return;
          }

          // Process specific event types.
          if (
            eventName === "message_result" &&
            eventData.type === 2 &&
            eventData.data &&
            eventData.data.messageResult
          ) {
            // Pass the message result to the event handler.
            eventHandler(eventName, eventData.data.messageResult);
          } else {
            // For any other events, pass the event name and full parsed data.
            eventHandler(eventName, eventData);
          }
        } catch (err) {
          console.error("Failed to parse event data:", err);
        }
      });

      // Return headers if external logic needs to extract additional information.
      return response.headers;
    } catch (error) {
      console.error(`Process SSE error: ${error.message}`);
      throw error;
    }
  }

  // Example usage:
  // Replace this with your own event handling logic.
  processSSE("https://api.useapi.net/v1/minimax/llm", { prompt: "tell me a joke" }, (eventName, eventData) => {
    // For example, simply log the event.
    console.log(`Event: ${eventName}`, eventData);
  });
```

</details>

##### Model `Content-Type: application/json`
```typescript
{ // TypeScript, all fields are optional
    request: {
        sendResult: {
            userMsgID: string
            chatID: string
            systemMsgID: string
            msgContent: string
            wordSpreadRate: number
            chatTitle: string
            canSearch: boolean
            canEdit: boolean
            extra: {
                form: {
                    formType: number
                    content: string
                    path?: string
                    fileID?: string
                    status?: number
                    fileByte?: number
                }[]
                longCutCopyWriting: string
            }
            isPreSendResult: boolean
        }
    }
    response: {
        messageResult: {
            msgID: string
            chatID: string
            msgType: string
            content: string
            requestStatus: number
            isEnd: number
            msgSubType: number
            parentMsgID: string
            extra: {
                netSearchStatus: {
                    finalStatus: {
                        statusCode: number
                    }
                }
                feedbackStatus: { [key: string]: unknown }
                replyMsgType: string
                warningText: string
            }
            canRetry: boolean
        }
    },
    error: {
        code: number
        httpCode: number
        message: string
        serviceTime: number
        requestID: string
        debugInfo: string
        serverAlert: number
    }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/llm" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/llm`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/llm" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create
## Create a video using an agent template
## Table of contents
<small>June 30, 2025 (August 21, 2025)</small>
---

Create videos using MiniMax agent templates with predefined prompts and input requirements. On average, it takes 2 to 7 minutes for the agent to complete generation. The longer the duration of the result video, the longer it will take to generate. Videos longer than 15 seconds on average can take up to 15 minutes to generate.

**Note:** This endpoint returns a **real-time streaming response** (`Content-Type: multipart/form-data`) that provides live progress updates during video generation.

Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

To browse available templates use [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates).
> **https://api.useapi.net/v1/minimax/videos/agent-create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

##### Response Headers
``` yaml
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax API account",
    "templateId": "Required template ID",
    "prompt": "Optional text prompt",
    "fileID": "user:user_id-minimax:account-file:file_id",
    "ossPath": "Required OSS path when using fileID",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 1
}
```

- `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts).  

- `templateId` is **required**, the ID of the agent template to use. Get available templates from [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates).

- `prompt` is optional, text input for templates that require text prompts. Check template requirements using [GET videos/agent-templates/?templateId=`templateId`](/docs/api-minimax-v1/get-minimax-videos-agent-templates) with the specific `templateId`.

- `fileID` is optional, required for templates that need image inputs:
    * fileID of image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files) 
    * fileID of previously uploaded image retrieved via [GET /files](/docs/api-minimax-v1/get-minimax-files) 
    * fileID of previously uploaded character retrieved via [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters)
    * fileID of image generated via [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

- `ossPath` is **required** when using `fileID`, the OSS path / url for the uploaded file. Cannot be provided without `fileID`.

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax video completed or failed.  
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used.  
  Valid range: 1…10.  

##### Responses 

**200**
**200 OK** 

Returns a **streaming response** (`Content-Type: text/event-stream`) with real-time progress updates. The stream contains multiple data events showing the video generation process from start to finish.

See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format.

```bash
data: {"status":"created","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800001000}

data: {"status":"connected","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","code":200,"timestamp":1755800002000}

data: {"status":"heartbeat","timestamp":1755800012000}

data: {"status":"progress","type":1,"message":{"msgContent":"Generating image...","msgType":2},"timestamp":1755800015000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800017000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"car.png","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../car.png"},"status":3}]}},"timestamp":1755800025000}

data: {"status":"progress","type":1,"message":{"msgContent":"Generating video...","msgType":2},"timestamp":1755800026000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800028000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"final_video.mp4","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../final.mp4"},"status":3}]}},"timestamp":1755800055000}

data: {"status":"progress","type":3,"isFinished":true,"recTemplateList":[{"id":"template_vlog_1","name":"Vlog Interview"},{"id":"template_tf_2","name":"Transformers"}],"timestamp":1755800056000}

data: {"status":"finished","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800057000}
```

Use the `videoId` from the stream event with `"status":"finished"` or `"status":"created"` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId).

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```

##### Model `Content-Type: text/event-stream`

See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format.

```bash
data:<JSON Data>

data:<JSON Data>

…
```

###### JSON Data Model
```typescript
{ // TypeScript, all fields are optional
  status?: 'created' | 'connected' | 'heartbeat' | 'progress' | 'finished' // Event status
  videoId?: string                     // Use GET /videos/<videoId> to retrieve results
  timestamp?: number                   // Event timestamp in milliseconds
  projectID?: string                   // Project identifier
  sectionID?: string                   // Section identifier within the project
  chatID?: string                      // Chat session identifier
  code?: number                        // Response code, e.g., 200
  type?: 1 | 2 | 3                     // Progress type. 1: Text/Tool, 2: Attachment, 3: Recommendations
  needUserInput?: boolean              // Flag indicating if user input is required
  isFinished?: boolean                 // Flag indicating if the entire process is complete
  errCode?: number                     // Error code, 0 for success
  errMsg?: string                      // Error message string
  /** The main message payload, can be null during certain events */
  message?: {
    msgId: string                      // Unique message ID
    parentMsgId?: string               // ID of the parent message
    msgType?: 1 | 2                    // Message type. 1: User, 2: System
    isQuota?: boolean                  // Quota usage flag
    timestamp?: number                 // Message creation timestamp
    msgContent?: string                // Text content of the message
    files?: {                          // User-uploaded files
      fileName: string
      fileUrl: string
      posterUrl: string
      type: string
      extra: Record<string, never>
    }[]
    toolCall?: {                       // System tool call details
      toolName: string
      toolCallStatus: 1 | 2            // Tool status. 1: Started, 2: Finished
      toolCallArgs: string             // Tool arguments as a JSON string
    }
    attachmentInfo?: {                 // Generated media attachments
      attachmentInfoID: string
      type?: 1 | 2 | 3                 // Attachment type. 1: Image, 2: Video, 3: Final Composite
      attachments: {
        attachmentID: string
        type?: number
        file: {
          fileName: string
          fileUrl: string
          posterUrl: string
          type: string
          extra?: {
            height?: string
            width?: string
            url?: string
            path?: string
            no_watermark_url?: string
            watermark_url?: string
            duration?: string
            fps?: string
            frames?: string            // A JSON string of frame URLs
            task_id?: string
            vendor?: string
          } | Record<string, never>
        }
        text?: string
        status?: 2 | 3                 // Generation status. 2: Processing, 3: Complete
        extra?: Record<string, never>
        subAttachments?: []
      }[]
      createTime?: number
      attachmentInfoUrl?: string
      extra?: Record<string, never>
      status?: number
    }
  } | null
}
```

##### Examples

**JavaScript**

<details markdown="block">

<summary>Expand <code class="language-plaintext highlighter-rouge"><b>JavaScript Streaming Example</b></code></summary>

``` javascript
const templateId = "1122334455667788";
const prompt = "text prompt";      
const token = "API token";

const response = await fetch('https://api.useapi.net/v1/minimax/videos/agent-create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: new FormData([['templateId', templateId], ['prompt', prompt]])
});

if (!response.ok) {
  const errorText = await response.text();
  throw new Error(`HTTP ${response.status}: ${errorText}`);
}

let videoId = null;
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop();
  
  for (const line of lines) {
    if (line.startsWith("data:")) {
      try {
        const json = JSON.parse(line.slice(5).trim());
        console.log("Stream event:", json);
        
        if (json.videoId && !videoId) {
          videoId = json.videoId;
          console.log("Video ID:", videoId);
        }
        
        if (json.status === 'finished') {
          console.log("Generation completed!");
          break;
        }
        
      } catch (e) {
        console.error("Failed to parse JSON:", e);
      }
    }
  }
}

console.log("Final video ID:", videoId);
```

</details>

**Python**

<details markdown="block">

<summary>Expand <code class="language-plaintext highlighter-rouge"><b>Python Streaming Example</b></code></summary>

``` python
import requests
import json

template_id = "1122334455667788"
prompt = "text prompt"      
token = "API token"

data = {
    'templateId': template_id,
    'prompt': prompt
}

response = requests.post(
    'https://api.useapi.net/v1/minimax/videos/agent-create',
    headers={'Authorization': f'Bearer {token}'},
    data=data,
    stream=True
)

if not response.ok:
    print(f"HTTP Error {response.status_code}: {response.text}")
    exit(1)

video_id = None

for line in response.iter_lines(decode_unicode=True):
    if line and line.startswith("data:"):
        try:
            json_data = json.loads(line[5:].strip())
            print("Stream event:", json_data)
            
            if json_data.get("videoId") and not video_id:
                video_id = json_data["videoId"]
                print(f"Video ID: {video_id}")
            
            if json_data.get("status") == "finished":
                print("Generation completed!")
                break
                
        except json.JSONDecodeError as e:
            print(f"Failed to parse JSON: {e}")

print(f"Final video ID: {video_id}")
```

</details>

**Curl**
``` bash
curl -H "Accept: text/event-stream" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/agent-create" \
     -d "templateId=1122334455667788" \
     -d "prompt=text prompt" \
     --no-buffer
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel
## Cancel the currently generated video
## Table of contents
<small>January 9, 2025</small>
---

Attempt to cancel a currently generated video created via [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).
> **https://api.useapi.net/v1/minimax/videos/cancel**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "videoId": "user:user_id-minimax:account-file:video_id",
}
```

- `videoId` is **required**. Specify the videoId you want to cancel.   

##### Responses 

**200**
**200 OK** 

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/cancel" \
     -d '{"videoId": "…"}'
```

**JavaScript**
``` javascript
const videoId = "videoId you want to cancel";      
const apiUrl = `https://api.useapi.net/v1/minimax/videos/cancel`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  videoId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoId = "videoId you want to cancel"   
apiUrl = f"https://api.useapi.net/v1/minimax/videos/cancel" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "videoId": f"{videoId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create
## Create a video using a text and image prompt
## Table of contents
<small>September 25, 2024 (May 4, 2026)</small>
---

Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

To upload prompt image use [POST /files](/docs/api-minimax-v1/post-minimax-files).

##### Model Comparison Matrix

###### Hailuo 01 — Legacy models, 720p 6sec, no `options`

| Model | Type | Notes |
|:------|:-----|:------|
| T2V-01 | Text-to-Video | Default for text prompts |
| I2V-01 | Image-to-Video | Default for image prompts |
| I2V-01-live | Image-to-Video | Live photo effect |
| I2V-01-Director | Image-to-Video | Camera movement control |
| T2V-01-Director | Text-to-Video | Camera movement control |
| S2V-01 | Subject Reference | Character/subject consistency |

###### Hailuo 02/2.3 — Resolution and duration `options`

| Model | Type | Options | End Frame |
|:------|:-----|:--------|:----------|
| 02 | Text/Image-to-Video | 512p-6/10sec, 768p-6/10sec, 1080p-6sec | Yes (768p/1080p) |
| T2V-2.3 | Text-to-Video | 768p-6/10sec, 1080p-6sec | No |
| I2V-2.3 | Image-to-Video | 768p-6/10sec, 1080p-6sec | No |
| I2V-2.3-Fast | Image-to-Video | 768p-6/10sec, 1080p-6sec | No |

###### Sora & Veo — `aspectRatio` (16:9, 9:16), higher resolution `options`

| Model | Type | Options | End Frame | Notes |
|:------|:-----|:--------|:----------|:------|
| Sora-2 | Text/Image-to-Video | 720p-4/8/12sec | No | OpenAI, exact 1280x720 or 720x1280 images |
| Veo-3.1 | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Google DeepMind, native audio |
| Veo-3.1-Fast | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Faster generation |
| Veo-3.1-S2V | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images |
| Veo-3.1-S2V-Fast | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images, faster |

###### Seedance 2.0 — Independent `resolution` + `duration`, `aspectRatio` (6 ratios), omni multi-modal references

| Model | Type | Resolutions | Duration | Aspect Ratios | Notes |
|:------|:-----|:-----------:|:--------:|:--------------|:------|
| Seedance-2.0 | Text/Image-to-Video | 480, 720, 1080 | 4–15 sec | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | ByteDance, omni reference + start/end frames |
| Seedance-2.0-Fast | Text/Image-to-Video | 480, 720 | 4–15 sec | Same as above | Faster, lower cost (no 1080p) |

Seedance models do not use `options`. Set `resolution` and `duration` directly. `end_frame_fileID` is mutually exclusive with omni references (`fileID2`…`fileID8`, `videoFileID*`, `audioFileID*`).

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Credits are charged per video. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing.

| Model | Option | Credits |
|:------|:-------|:-------:|
| T2V-01, I2V-01, I2V-01-live, S2V-01, T2V-01-Director, I2V-01-Director | - | 25 |
| 02, T2V-2.3, I2V-2.3 | 768p-6sec | 25 |
| 02, T2V-2.3, I2V-2.3 | 768p-10sec | 50 |
| 02, T2V-2.3, I2V-2.3 | 1080p-6sec | 80 |
| 02 | 512p-6sec | 12 |
| 02 | 512p-10sec | 25 |
| I2V-2.3-Fast | 768p-6sec | 15 |
| I2V-2.3-Fast | 768p-10sec | 30 |
| I2V-2.3-Fast | 1080p-6sec | 50 |
| Sora-2 | 720p-4sec | 40 |
| Sora-2 | 720p-8sec | 80 |
| Sora-2 | 720p-12sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-720p-8sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-1080p-8sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-4k-8sec | 180 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-720p-8sec | 60 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-1080p-8sec | 60 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-4k-8sec | 90 |

Seedance models are billed **per second**. Multiply the rate by your chosen `duration` (4–15) for total credits.

| Model | Resolution | T2V (credits/sec) | I2V or omni (credits/sec) |
|:------|:----------:|:-----------------:|:-------------------------:|
| Seedance-2.0-Fast | 480p | 4 | 7 |
| Seedance-2.0-Fast | 720p | 10 | 15 |
| Seedance-2.0 | 480p | 5 | 9 |
| Seedance-2.0 | 720p | 12 | 19 |
| Seedance-2.0 | 1080p | 27 | 45 |

</details>
> **https://api.useapi.net/v1/minimax/videos/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body

```json
{
    "account": "1234567890",
    "model": "Seedance-2.0-Fast",
    "fileID": "user:1234-minimax:1234567890-file:1234567890",
    "prompt": "Cinematic shot of @Image1 walking through a neon-lit alley at night, rain reflections on wet pavement, slow tracking",
    "resolution": "720",
    "duration": 5,
    "aspectRatio": "16:9",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "shot-042"
}
```

- `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts).  

- `prompt` is optional, describe your shot. Maximum length 2,000 characters. How to prompt [tutorial](https://ageofllms.com/ai-howto-prompts/ai-fun/hailuo-minimax-tutorial).

  **Seedance `@`-mentions.** When omni references are uploaded, you can refer to them in the prompt using `@Image1`…`@Image8`, `@Video1`…`@Video3`, `@Audio1`…`@Audio3` (case-insensitive — `@image1`, `@IMAGE1`, `@Image01` all resolve to the same slot). Unresolved tokens (e.g. `@Image5` when only 2 images are provided) return a 400 error. If no omni references are uploaded, `@`-tokens pass through as literal text.

- `promptOptimization` is optional.
  Supported values: `true`, `false`. Default: `false` (no optimization).

- `fileID` — image/character reference. Upload via [POST /files](/docs/api-minimax-v1/post-minimax-files), retrieve via [GET /files](/docs/api-minimax-v1/get-minimax-files), [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters), or use fileID from [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

  | `model` | `fileID` | `end_frame_fileID` | `fileID2`…`fileID14` | `aspectRatio` |
  |:------|:---------|:-------------------|:---------------------|:--------------|
  | `T2V-01`, `T2V-01-Director`, `T2V-2.3` | Not supported | - | - | - |
  | `I2V-01`, `I2V-01-live`, `I2V-01-Director` | Required | - | - | - |
  | `S2V-01` | Required | - | - | - |
  | `02` | Optional | Yes (768p/1080p only) | - | - |
  | `I2V-2.3`, `I2V-2.3-Fast` | Required | - | - | - |
  | `Sora-2` | Optional (exact 1280x720 or 720x1280) | - | - | `16:9`, `9:16` |
  | `Veo-3.1`, `Veo-3.1-Fast` | Optional | Yes | - | `16:9`, `9:16` |
  | `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` | Required | - | Up to 14 total | `16:9`, `9:16` |
  | `Seedance-2.0`, `Seedance-2.0-Fast` | Optional | Yes (mutually exclusive with `fileID2`…`fileID8` and omni `videoFileID*`/`audioFileID*`) | Up to 8 (`fileID`…`fileID8`, resolved as `@Image1`…`@Image8`) | 6 ratios (see below) |

- `end_frame_fileID` is optional. The `end_frame_fileID` and `fileID` cannot be the same, reupload the end frame via [POST /files](/docs/api-minimax-v1/post-minimax-files) if needed.

- `fileID2` … `fileID14` are optional. **For S2V models** (`Veo-3.1-S2V`, `Veo-3.1-S2V-Fast`) — additional subject/character reference images, up to 14 total. **For Seedance models** (`Seedance-2.0`, `Seedance-2.0-Fast`) — additional omni image references `@Image2`…`@Image8` (up to 8 total; `fileID9`…`fileID14` rejected). Requires `fileID` first. Slots must be filled consecutively (no gaps). All files must belong to the same account.

- `videoFileID1` … `videoFileID3` are optional, **for Seedance models only**. Omni video references resolved as `@Video1`…`@Video3` in the prompt. Upload mp4 via [POST /files](/docs/api-minimax-v1/post-minimax-files). Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`.

- `audioFileID1` … `audioFileID3` are optional, **for Seedance models only**. Omni audio references resolved as `@Audio1`…`@Audio3` in the prompt. Upload mp3 or wav via [POST /files](/docs/api-minimax-v1/post-minimax-files). Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`.

- `resolution` is optional, **for Seedance models only**. Supported values: `480`, `720`, `1080` (full Seedance-2.0 only). Default: `720`.

- `duration` is optional, **for Seedance models only**. Integer seconds in range 4–15. Default: `5`.

- `aspectRatio` is optional. Supported by:
  - `Sora-2`, `Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` — values: `16:9` (default), `9:16`.
  - `Seedance-2.0`, `Seedance-2.0-Fast` — values: `21:9`, `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`.

- `model` is optional. Supported values:

  **Hailuo 01** — 720p, 6 sec
  * `T2V-01` (default) text-to-video
  * `I2V-01` (default) image-to-video
  * `I2V-01-live` image-to-video, live photo effect
  * `S2V-01` subject reference, character/subject consistency
  * `T2V-01-Director` text-to-video, camera movement control via `[<movement>]` in prompt (instructions)
  * `I2V-01-Director` image-to-video, camera movement control via `[<movement>]` in prompt (instructions)

  **Hailuo 02/2.3** — resolution and duration `options`
  * `02` text/image-to-video, native 1080p
  * `T2V-2.3` text-to-video
  * `I2V-2.3` image-to-video
  * `I2V-2.3-Fast` image-to-video, faster generation

  **Sora & Veo** — `aspectRatio` support, higher resolution `options`
  * `Sora-2` OpenAI Sora 2, text/image-to-video, 720p only. Image: exact 1280x720 (16:9) or 720x1280 (9:16)
  * `Veo-3.1` Google DeepMind Veo 3.1, text/image-to-video with native audio, 720p/1080p/4K
  * `Veo-3.1-Fast` Veo 3.1 Fast, text/image-to-video, 720p/1080p/4K
  * `Veo-3.1-S2V` Veo 3.1 Subject Reference, up to 14 reference images via `fileID`…`fileID14`, 720p/1080p/4K
  * `Veo-3.1-S2V-Fast` Veo 3.1 Subject Reference Fast, up to 14 reference images, 720p/1080p/4K

  **Seedance 2.0** — independent `resolution` + `duration`, omni multi-modal references, 6 aspect ratios
  * `Seedance-2.0` ByteDance Seedance 2.0, text/image-to-video, 480p/720p/1080p, 4–15 sec
  * `Seedance-2.0-Fast` Seedance 2.0 Fast, text/image-to-video, 480p/720p, 4–15 sec, lower cost

- `options` is optional. Sets resolution and duration. Hailuo 01 and Seedance models do not support `options` (Seedance uses `resolution` and `duration` directly).

  | `model` | `options` | `end_frame` |
  |:------|:-------------------|:-----------|
  | `02` | `512p-6sec`, `512p-10sec` (I2V only), `768p-6sec`, `768p-10sec`, `1080p-6sec` | Yes (768p/1080p only) |
  | `T2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `I2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `I2V-2.3-Fast` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `Sora-2` | `720p-4sec`, `720p-8sec`, `720p-12sec` | No |
  | `Veo-3.1` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes |
  | `Veo-3.1-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes |
  | `Veo-3.1-S2V` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No |
  | `Veo-3.1-S2V-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No |

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax video completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used.  
  Valid range: 1…10.  
  Please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue.  

##### Responses 

**200**
**200 OK** 

Use returned `videoId` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated video with the `status` **2** (Completed).

If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-videos-create#request-body) the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "id": "1122334455667798899",
    "task": {
        "batchID": "998877665544332211",
        "videoIDs": [
            "1122334455667798899"
        ]
    },
    "videoId": "user:1234-minimax:987654321-video:998877665544332211",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. Please recharge to get more credits or try again next day.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new videos/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": "Account <MiniMax account> is busy executing <Account maxJobs> videos",
    "runningVideos": {
        "<MiniMax account>": [
            {
                "account": "<MiniMax account>",
                "id": "id1",
                "scheduledVideo": "<scheduled video id1>",
                "videoId": "user:user_id-minimax:account-video:id1",
                "started": "2024-09-25T01:55:16.128Z",
                "replyUrl": "<optional callback URL>",
                "replyRef": "<optional reference>"
            },
            {
                "account": "<MiniMax account>",
                "id": "idN",
                "scheduledVideo": "<scheduled video idN>",
                "videoId": "user:user_id-minimax:account-video:idN",
                "started": "2024-09-25T01:55:16.128Z",
                "replyUrl": "<optional callback URL>",
                "replyRef": "<optional reference>"
            }
        ]
    }
}
```
2. The API received an HTTP response status 429 from MiniMax. Please refer to your [subscription](https://hailuoai.video/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "YOU CAN QUEUE 3 JOBS AT ONCE"
}
```

**596**
**596 Pending mod message** 

Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked.  Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    videoId: string
    id: string
    task: {
        batchID: string
        videoIDs: string[]
    }
    runningVideos: {
      [account: string]: {
        account: string
        id: string
        scheduledVideo: string
        videoId: string
        started: string 
        replyUrl: string 
        replyRef: string 
      }[]
    }
    replyUrl: string
    replyRef: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/videos/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/videos/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/wss-minimax-audio-wss ===
Document URL: https://useapi.net/docs/api-minimax-v1/wss-minimax-audio-wss
## Create text-to-speech audio stream over the WebSocket
## Table of contents
<small>January 7, 2025 (August 21, 2025)</small>

<span class="required-input-field"><b>This version of MiniMax audio has been decommissioned. Consider switching to <a href="/docs/api-mureka-v1">Mureka API</a></b></span>
---

Use [POST audio/create-stream](/docs/api-minimax-v1/post-minimax-audio-create-stream) to obtain `token` and `payload`.   
To see the provided below code in action use [Try It](/docs/api-minimax-v1/post-minimax-audio-create-stream#try-it).  
> **wss://api.useapi.net/v1/minimax/audio/wss?token=`token`**

##### Query Parameters

- `token` is **required**. Use [POST audio/create-stream](/docs/api-minimax-v1/post-minimax-audio-create-stream) to obtain `token`.

##### Responses 

**101**
**101 Switching Protocols** 

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

##### Examples

```javascript
var player = null;
var ws = null;

const urlCreateStream = 'https://api.useapi.net/v1/minimax/audio/create-stream';
const wssCreateStream = 'wss://api.useapi.net/v1/minimax/audio/wss';
const urlAudio = 'https://api.useapi.net/v1/minimax/audio';

class DynamicAudioPlayer {
    constructor() {
        this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
        this.audioQueue = [];
        this.isPlaying = false;
        this.currentSource = null;
        this.onAudioFinishedCallback = null;
    }

    async loadAudioData(base64Chunk, finishCallback) {
        try {
            const byteArray = this.hexStringToByteArray('fffbe8c4' + base64Chunk);
            this.audioQueue.push(byteArray);
            this.onAudioFinishedCallback = finishCallback;

            if (!this.isPlaying) {
                this.isPlaying = true;
                await this.playNextChunk();
            }
        } catch (e) {
            console.error("Error decoding audio data:", e);
        }
    }

    async playNextChunk() {
        if (this.audioQueue.length > 0) {
            const byteArray = this.audioQueue.shift();
            const audioBuffer = await this.audioContext.decodeAudioData(byteArray.buffer);
            this.scheduleAudioBuffer(audioBuffer);
        } else {
            this.isPlaying = false;
            if (this.onAudioFinishedCallback) {
                this.onAudioFinishedCallback();
                this.onAudioFinishedCallback = null;
            }
        }
    }

    scheduleAudioBuffer(audioBuffer) {
        const source = this.audioContext.createBufferSource();
        source.buffer = audioBuffer;
        source.connect(this.audioContext.destination);
        source.start();
        this.currentSource = source;

        source.onended = () => {
            this.playNextChunk();
        };
    }

    stop() {
        this.audioQueue = [];
        if (this.currentSource) {
            this.currentSource.stop();
            this.currentSource = null;
        }
        this.isPlaying = false;
    }

    hexStringToByteArray(hexString) {
        const bytes = new Uint8Array(hexString.length / 2);
        for (let i = 0; i < hexString.length; i += 2) {
            bytes[i / 2] = parseInt(hexString.substring(i, i + 2), 16);
        }
        return bytes;
    }
}

async function streamAudio(data, callback, finishCallback) {
    const parseData = async (wssData) => {
        try {
            const json = JSON.parse(wssData);

            // Added March 17, 2025
            // Error occurred.
            if(json.data?.status === undefined && json.statusInfo?.code !== 0) {
                callback({ status: json.statusInfo.code, json, text: '🛑 ' + json.statusInfo?.message });
                ws.close();
                ws = null;
                finishCallback();
                return;
            }

            let audio;

            if (json.data?.audio) {
                audio = json.data.audio;
                json.data.audio = `…omitted ${audio.length} bytes of raw audio…`;
            }

            if (json.data?.status == 1 && audio)
                player.loadAudioData(audio, finishCallback);

            if (callback)
                callback({ status: 200, json });

            if (json.data?.status == 2) {
                const { headers, body } = data;
                const { account } = JSON.parse(body);

                callback({ text: `⌛ GET ${urlAudio} ⁝ looking for generated mp3…` });

                const response = await fetch(`${urlAudio}${account ? '/?account=' + account : ''}`, { headers });

                const text = await response.text();

                if (!response.ok) {
                    callback({ status: response.status, text });
                    return;
                }

                const { audio_list } = JSON.parse(text);

                const item = audio_list?.at(0);

                const { audio_url } = item ?? {};

                callback({ status: response.status, json: item, text: '👉🏻 ' + audio_url });
            }
        } catch (error) {
            console.error(`Failed to parse JSON: ${error}`, wssData);
        }
    };

    if (player)
        player.stop();
    else
        player = new DynamicAudioPlayer();

    if (ws) {
        ws.close();
        ws = null;
    }

    callback({ text: `⏳ Requesting WebSocket token and payload from ${urlCreateStream}…` });

    const response = await fetch(urlCreateStream, data);

    const text = await response.text();

    callback({ status: response.status, text });

    if (!response.ok)
        return;

    const { token, payload } = JSON.parse(text);

    callback({ text: `⌛ Establishing WebSocket connection to ${wssCreateStream}…` });

    ws = new WebSocket(`${wssCreateStream}/?token=${token}`);

    ws.addEventListener('open', () => {
        callback({ text: `🚀 Sending payload over WebSocket connection` });
        // Updated March 17, 2025
        ws.send(JSON.stringify(payload));
    });

    ws.addEventListener('message', async event => {
        await parseData(event.data);
    });

    ws.addEventListener('error', event => {
        const text = `🛑 WebSocket error: ${JSON.stringify(event)}`;
        console.error(text);
        callback({ text });
    });

    ws.addEventListener('close', event => {
        console.log('WebSocket close', event);
    });
}

// Here's how you call above functions

const data = {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${api_token_value}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        text: 'your text goes here',
        voice_id: 'desired voice'
    })
};

await streamAudio(
    data,
    // optional progress callback
    (status, json, text) => {
        console.log(`callback`, { status, json, text });
    },
    // optional playback completed callback
    () => {
        console.log(`playback completed`);
    }
);    
```

##### Model 

The below model represent WebSocket message payload object.  
The value of `data.status` can be either `1` (progress) or `2` (completed).
Once generation is completed, you can locate the generated `mp3` file in `audio_list[]` returned by the [GET audio](/docs/api-minimax-v1/get-minimax-audio) endpoint. It will be the last returned item or alternatively, you can match on text.

```typescript
{ // TypeScript, all fields are optional
  data: {
    audio: string
    status: number
    ced: string
  }
  extra_info?: {
    audio_length: number
    audio_sample_rate: number
    audio_size: number
    bitrate: number
    word_count: number
    invisible_character_ratio: number
    usage_characters: number
    audio_format: string
    audio_channel: number
  }
  input_sensitive: boolean
  trace_id: string
  base_resp: {
    status_code: number
    status_msg: string
  }
}
```

=== URL: https://useapi.net/docs/start-here/setup-mureka ===
Document URL: https://useapi.net/docs/start-here/setup-mureka
# <img style="height:1.2em;vertical-align: middle;" src="/assets/images/mureka.webp"> Setup Mureka
<small>December 2, 2024 (April 13, 2026)</small>
> Looking for the [legacy setup method](/docs/start-here/setup-mureka-legacy)?

## Table of contents
<small>Approximately 10 minutes to complete setup steps.</small>

---
> This is the setup guide for [Mureka API](/docs/api-mureka-v1). A [Mureka AI](https://www.mureka.ai) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

### Automated setup (recommended)

Use our guided browser setup to configure your account automatically — no DevTools or cookie copying needed. Enter your API token, log in with Google in the remote browser, and your account is ready.

[Open automated setup](/assets/setup-browser/mureka.html){: .btn .btn-primary .fs-4 }

<small>Prefer manual setup? Continue with the steps below.</small>

---

[Mureka AI](https://www.mureka.ai), a **music generation** service from Chinese tech giant Kunlun Tech featuring proprietary SkyMusic 2.0 model and positioned to compete with [Suno](https://www.suno.com) and [Udio](https://www.udio.com). Mureka AI creates unique songs based on user-provided lyrics or description (AI-generated lyrics), selected musical styles, and references to specific vocals and songs, including those uploaded by the user.

### Create Gmail account

We *strongly recommend* creating a separate new Gmail account designated to be used with the API. When creating the account make sure to turn on [2-Step Verification](https://support.google.com/accounts/answer/185839) authorization using [Google Authenticator](https://support.google.com/accounts/answer/1066447).

### Clear all browser cookies

Launch Chromium-based web-browser of your choice (eg [Opera](https://www.opera.com/), [Brave](https://brave.com/), [Chromium](https://www.chromium.org/) or [Chrome](https://www.google.com/chrome/)) and clear **all** cookies.
It is very important that you start absolutely fresh and obtain fresh Google cookies.

We suggest using [Opera](https://www.opera.com/) with `VPN` option turned on and VPN region set to Americas.

1. Open a new browser tab
2. Click on the address bar and type `opera://settings/clearBrowserData` (or `chrome://settings/clearBrowserData` for Chrome) <span style="color: red;">`1`</span>
3. Press `Enter` to navigate to the settings page
4. Set `Time range` to `All time`
5. Check `Cookies and other site data` <span style="color: red;">`2`</span>
6. Click `Delete data` <span style="color: red;">`3`</span>

![](/assets/images/mureka_setup_1.jpg)

### Navigate to Mureka and login with Google

* Navigate to [https://www.mureka.ai](https://www.mureka.ai) <span style="color: red;">`1`</span>
* Click on `Try free now` button <span style="color: red;">`2`</span>

![](/assets/images/mureka_setup_2.jpg)

* Click `Continue with Google` button

![](/assets/images/mureka_setup_3.jpg)

* Enter your Google email created earlier

![](/assets/images/mureka_setup_4.jpg)

* Enter 2-Step Verification code <span style="color: red;">`1`</span>
* Make sure to check `Don't ask again on this device` <span style="color: red;">`2`</span> - this is **very important**
* Click `Next` <span style="color: red;">`3`</span>

![](/assets/images/mureka_setup_5.jpg)

Once successfully logged in you should see your user profile in the sidebar

![](/assets/images/mureka_setup_6.jpg)

### Navigate to Google Account

* Click on the address bar
* Type or paste `myaccount.google.com` <span style="color: red;">`1`</span>
* Press `Enter` to navigate

![](/assets/images/mureka_setup_7.jpg)

### Copy `__Secure-3PSID` cookie

Now we need to open Developer Tools to copy the cookie:

1. Press `F12` key on your keyboard (or `Control+Shift+I` on Windows, `Command+Option+I` on Mac)
2. A panel will open on the right side or bottom of your browser - this is Developer Tools
3. Look at the top of this panel and find the word `Application` - click on it <span style="color: red;">`1`</span>
4. On the left side of the panel, find `Cookies` - click the small arrow next to it to expand
5. Click on `https://accounts.google.com/` <span style="color: red;">`2`</span>
6. A list of cookies will appear on the right side
7. Scroll through the list and find the cookie named `__Secure-3PSID`
8. Click once on that row to select it (the row will become highlighted) <span style="color: red;">`3`</span>
9. Right-click on the highlighted row
10. A menu will appear - click on `Copy` <span style="color: red;">`4`</span>

![](/assets/images/mureka_setup_8.jpg)

Your copied cookie will look similar to this (tab-separated values):

```
__Secure-3PSID	g.a0...secured...076	.google.com	/	2027-02-23T04:38:16.033Z	167	✓	✓	None			High
```

We redacted values in the screenshot for security, your actual cookie value will be a long string (~170 characters).

### Verify and add account

Use the form below to verify your cookie and add your Mureka account. Paste the copied cookie into the `sessionCookie` field.

**Option 1: Paste the full tab-separated cookie line** (as copied from DevTools):
```
__Secure-3PSID	g.a0...secured...076	.google.com	/	2027-02-23T04:38:16.033Z	167	✓	✓	None			High
```

**Option 2: Paste minimal JSON format** (if you prefer):
```json
{"value": "g.a0...secured...076", "expires": "2027-02-23T04:38:16.033Z"}
```

Select **Add Account** to complete setup, or **Verify** to test your cookie first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) directly.

⚠️ Once your account is added, make sure to [clear all browser cookies](#clear-all-browser-cookies) to ensure that this session will no longer be active in the browser and fully managed by API.

<script>
  async function apiTestAccountMureka(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-Mureka-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let sessionCookie = document.getElementById(`post-accounts-Mureka-sessionCookie`)?.value;

      const body = { sessionCookie };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/mureka/accounts`, 'post-accounts-Mureka', data);
  }
</script>

<form id="post-accounts-Mureka" onsubmit="apiTestAccountMureka(document.getElementById('post-accounts-Mureka-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Mureka-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Mureka-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Mureka-sessionCookie"><span>sessionCookie<small> (paste __Secure-3PSID cookie)</small></span>
        <textarea id="post-accounts-Mureka-sessionCookie" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea>
      </label>
      <label for="post-accounts-Mureka-action"><span>action</span>
        <select id="post-accounts-Mureka-action" class="input-element">
          <option value="verify">Verify — test cookie only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Mureka-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-Mureka-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-mureka-v1 ===
Document URL: https://useapi.net/docs/api-mureka-v1

# <img style="height:1.2em;vertical-align: middle;" src="/assets/images/mureka.webp"> Mureka API v1

<small>December 2, 2024 (April 4, 2026)</small>

This is [experimental](/docs/legal) API for for the [Mureka AI](https://www.mureka.ai), a music generation service from Chinese tech giant Kunlun Tech featuring proprietary SkyMusic 2.0 model and positioned to compete with [Suno](https://www.suno.com) and [Udio](https://www.udio.com). Mureka AI creates unique songs based on user-provided lyrics or description (AI-generated lyrics), selected musical styles, and references to specific vocals and songs, including those uploaded by the user.

Our API also provides comprehensive **TTS/speech generation** capabilities with custom voice cloning from audio samples and multi-turn conversations using multiple voices.

Our API supports **all** functionality of [Mureka AI](https://www.mureka.ai), including Pro subscription features such as the ability to upload and use custom soundtracks for reference, and to upload and use melodies (motifs). 

Mureka supports up to **10 concurrent generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your lyrics.

Currently, two [web subscription](https://www.mureka.ai/subscribe) plans are supported:

| Plan | Price | Songs | Speech |
|------|-------|-------|--------|
| **Pro** | $9/month | 500 songs | 250 min |
| **Premier** | $27/month | 2,000 songs | 1,000 min |

Cost breakdown:

| Plan | Cost/Song | Cost/Speech Min |
|------|-----------|-----------------|
| **Pro** | 1.8¢ | 3.6¢ |
| **Premier** | 1.35¢ | 2.7¢ |

Supported models: `V9` (default), `V8`, `O2`, `V7.6`, `V7.5`

* Song/speech allowances are **shared** (songs OR speech minutes)
* Downloading instrumentals and stems is **free**
* Lyrics generation is **free**

Credit top-ups available at $48 for 1600 credits.

Compare the above with the official API, which starts at [$1000/m with 5 concurrent generations](https://platform.mureka.ai/pricing) at a rate of `3¢/song`. The official API also charges for lyrics generation and stems download.

[Setup Mureka](/docs/start-here/setup-mureka)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(April 4, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-mureka-v1.txt) <small>Feed this to your LLM to build integrations</small>

Examples:

* [Mureka V9](/blog/260404)
* [Mureka V8](/blog/260127m)
* [Mureka O2 & V7.6](/blog/251128)
* [Mureka TTS/Speech](/blog/250818)

Articles:
* [Mureka API Music Samples](/docs/articles/mureka-music-samples)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/murekaai_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/murekaai_api</a>

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-accounts-account ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-accounts-account
## Delete Mureka API account
<small>December 2, 2024</small>

---
> **https://api.useapi.net/v1/mureka/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/mureka/accounts/<account> 
```

**JavaScript**
``` javascript
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Previously configured account" 
apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{account}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files-vocal ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files-vocal
## Delete vocal
<small>January 15, 2025</small>

---

Delete vocal which was uploaded using [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal).
> **https://api.useapi.net/v1/mureka/files/vocal/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `id` is **required**, to see full list of uploaded vocals use [GET music/vocals/?mine=true](/docs/api-mureka-v1/get-mureka-music-vocals).

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/mureka/files/vocal/?account=<accound>&id=<id>
```

**JavaScript**
``` javascript
const account = 123456789; 
const id = 98765432; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/vocal/?account=${account}&id=${id}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = 123456789
id = 98765432
apiUrl = f"https://api.useapi.net/v1/mureka/files/vocal/?account={account}&id={id}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files
## Delete track
<small>December 13, 2024</small>

---

Delete track which was uploaded using [POST /files](/docs/api-mureka-v1/post-mureka-files).
> **https://api.useapi.net/v1/mureka/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `id` is **required**, to see full list of uploaded tracks use [GET /files](/docs/api-mureka-v1/get-mureka-files).

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/mureka/files/?account=<accound>&id=<id>
```

**JavaScript**
``` javascript
const account = 123456789; 
const id = 98765432; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}&id=${id}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = 123456789
id = 98765432
apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}&id={id}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-song_id ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-song_id
## Delete song
<small>December 2, 2024</small>

---
> **https://api.useapi.net/v1/mureka/music/`song_id`**

The `song_id` value returned by one of the following endpoints: 
* [GET /music](/docs/api-mureka-v1/get-mureka-music)
* [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
* [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
* [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)   

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  

```json
{}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/mureka/accounts/<song_id> 
```

**JavaScript**
``` javascript
const song_id = 123456789; 
const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${song_id}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
song_id = 123456789
apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{song_id}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech-voice ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech-voice
## Delete speech voice
<small>August 18, 2025</small>

---

This endpoint permanently deletes a custom cloned voice from your Mureka account. Once deleted, the voice cannot be recovered and can no longer be used for speech generation. Use this to clean up unwanted voice clones or manage your voice library.
> **https://api.useapi.net/v1/mureka/speech/voice?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `voice_id` is **required**. The ID of the voice to delete.  
  Get voice IDs from [GET /speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices).

##### Responses 

**200**
**200 OK**  

```json
{}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/mureka/speech/voice?voice_id=12345678901234" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const voiceId = "Voice ID to delete";
const apiUrl = `https://api.useapi.net/v1/mureka/speech/voice?voice_id=${voiceId}`; 
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
voice_id = "Voice ID to delete"
apiUrl = f"https://api.useapi.net/v1/mureka/speech/voice?voice_id={voice_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech
## Delete speech
<small>August 18, 2025</small>

---

This endpoint permanently deletes a specific speech recording from your Mureka account. Once deleted, the speech audio file and metadata cannot be recovered. Use this to clean up unwanted recordings or manage storage in your account.
> **https://api.useapi.net/v1/mureka/speech/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `id` is **required**. The ID of the speech to delete.  
  Get speech IDs from [GET /speech](/docs/api-mureka-v1/get-mureka-speech).

##### Responses 

**200**
**200 OK**  

```json
{}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/mureka/speech/?id=23456789012345" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const speechId = "Speech ID to delete";
const apiUrl = `https://api.useapi.net/v1/mureka/speech/?id=${speechId}`; 
const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
speech_id = "Speech ID to delete"
apiUrl = f"https://api.useapi.net/v1/mureka/speech/?id={speech_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts-account ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts-account
## Retrieve Mureka API account configuration for `account` 
<small>December 2, 2024 (January 20, 2026)</small>

---

[Setup Mureka](/docs/start-here/setup-mureka)
> **https://api.useapi.net/v1/mureka/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "account": "123456789",
    "token": "abc…secured…xyz",
    "updated": 1724514995,
    "updatedUTC": "2024-10-24T15:56:35.000Z",
    "tokenIssuedDaysAgo": 30,
    "hasAutoRefresh": true,
    "email": "user@gmail.com",
    "sessionCookie": {
        "name": "__Secure-3PSID",
        "value": "g.a000abc…secured…12345",
        "domain": ".google.com",
        "path": "/",
        "expires": "2026-02-15T12:00:00.000Z",
        "httpOnly": true,
        "secure": true,
        "sameSite": "None",
        "added": "2026-01-15T10:30:00.000Z"
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model
```typescript
{ // TypeScript, all fields are optional
    account: string
    token: string
    updated: number
    updatedUTC: string
    tokenIssuedDaysAgo: number
    hasAutoRefresh: boolean
    email?: string
    sessionCookie?: {
        name: string
        value: string
        domain: string
        path: string
        expires: string
        httpOnly: boolean
        secure: boolean
        sameSite: string
        added?: string
    }
    error?: string
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/mureka/accounts/<account> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts
## Retrieve Mureka API accounts configuration
<small>December 2, 2024 (January 20, 2026)</small>

---

This endpoint retrieves the complete list of configured API accounts for Mureka.

[Setup Mureka](/docs/start-here/setup-mureka)
> **https://api.useapi.net/v1/mureka/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "123456789": {
    "account": "123456789",
    "token": "abc…secured…xyz",
    "updated": 1724514995,
    "updatedUTC": "2024-10-24T15:56:35.000Z",
    "tokenIssuedDaysAgo": 29,
    "hasAutoRefresh": true,
    "email": "user@gmail.com",
    "sessionCookie": {
      "name": "__Secure-3PSID",
      "value": "g.a000abc…secured…12345",
      "domain": ".google.com",
      "path": "/",
      "expires": "2026-02-15T12:00:00.000Z",
      "httpOnly": true,
      "secure": true,
      "sameSite": "None",
      "added": "2026-01-15T10:30:00.000Z"
    }
  },
  "987654321": {
    "account": "987654321",
    "token": "def…secured…uvw",
    "updated": 1724514995,
    "updatedUTC": "2024-10-24T15:56:35.000Z",
    "tokenIssuedDaysAgo": 1,
    "hasAutoRefresh": false,
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required"
  }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model
```typescript
{ // TypeScript, all fields are optional
    [account: string]: {
        account: string
        token: string
        updated: number
        updatedUTC: string
        tokenIssuedDaysAgo: number
        hasAutoRefresh: boolean
        email?: string
        sessionCookie?: {
            name: string
            value: string
            domain: string
            path: string
            expires: string
            httpOnly: boolean
            secure: boolean
            sameSite: string
            added?: string
        }
        error?: string
    }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/mureka/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/mureka/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/mureka/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files-youtube ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files-youtube
## Retrieve soundtrack from YouTube url
<small>December 13, 2024</small>

---

This endpoint will return a link to the YouTube video soundtrack. You can download it, adjust if needed, and upload it to your track collection using [POST /files](/docs/api-mureka-v1/post-mureka-files).
> **https://api.useapi.net/v1/mureka/files/youtube/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `url` is **required**. Provide the YouTube url link for which you want to retrieve the soundtrack.

##### Responses 

**200**
**200 OK**  

```json
{
    "name": "<YouTube video name>",
    "cos_url": "https://...mp3",
    "duration": 21000
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  name: string
  cos_url: string
  duration: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/files/youtube/?account=account&url=<url>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const url = "YouTube video url"; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/youtube/?account=${account}&url=${url}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
url = "YouTube video url"
apiUrl = f"https://api.useapi.net/v1/mureka/files/youtube/?account={account}&url={url}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files
## Retrieve your reference tracks
<small>December 13, 2024</small>

---

Retrieve full list of track uploaded using [POST /files](/docs/api-mureka-v1/post-mureka-files). Keep in mind that all uploaded files will be visible to all users of Mureka.ai website.

Use `id` value to reference a track when using the parameter `ref_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced).
> **https://api.useapi.net/v1/mureka/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`.  

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "id": 1122334455,
            "url": "https://<song download url>.mp3",
            "duration_milliseconds": 30000,
            "mood": "relaxed",
            "title": "<song title>",
            "genre": "afrobeat",
            "username": "<user name>"
        },
        {
            "id": 66778899,
            "url": "https://<song download url>.mp3",
            "duration_milliseconds": 30000,
            "mood": "restless",
            "title": "<song title>",
            "genre": "rock",
            "username": "<user name>"
        }
    ],
    "last_id": 77665544332211,
    "more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        id: number
        url: string
        duration_milliseconds: number
        mood: string
        title: string
        genre: string
        username: string
    }[]
    last_id: number
    more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/files/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs-jobid ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs-jobid
## Retrieve Job Status
<small>January 21, 2026</small>

---

Retrieve the status and details of a specific music or speech generation job by its job ID.

This endpoint is particularly useful when using `async` mode for music or speech generation, or when tracking job progress via webhooks using the `replyUrl` parameter.

Job IDs are returned from:
* [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
* [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)
* [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
* [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend)
* [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate)
* [POST /speech](/docs/api-mureka-v1/post-mureka-speech)

Jobs are retained for 7 days after creation. Jobs older than 7 days will return a 404 error.

To get a summary of all running jobs, use [GET /jobs](/docs/api-mureka-v1/get-mureka-jobs).
> **https://api.useapi.net/v1/mureka/jobs/`jobid`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `jobid` is **required**, the unique job identifier.

##### Responses

**200**
**200 OK**

Returns the job record with current status and details.

**Music job (completed):**

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create",
    "jobType": "music",
    "status": "completed",
    "created": "2026-01-20T12:34:56.789Z",
    "updated": "2026-01-20T12:35:42.123Z",
    "request": {
        "account": "12345678901234",
        "prompt": "Upbeat electronic dance track",
        "model": "V7.6",
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    },
    "response": {
        "feed_id": 11223344,
        "state": 3,
        "songs": [
            {
                "song_id": "user:777-mureka:123456789-song:33445566",
                "title": "Upbeat Dance",
                "version": "1",
                "duration_milliseconds": 234567,
                "mp3_url": "https://...mp3",
                "cover": "https://...png"
            },
            {
                "song_id": "user:777-mureka:123456789-song:33445567",
                "title": "Upbeat Dance",
                "version": "2",
                "duration_milliseconds": 234890,
                "mp3_url": "https://...mp3",
                "cover": "https://...png"
            }
        ]
    }
}
```

**Speech job (completed):**

```json
{
    "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka",
    "verb": "speech",
    "jobType": "tts",
    "status": "completed",
    "created": "2026-01-20T12:40:00.000Z",
    "updated": "2026-01-20T12:40:25.000Z",
    "request": {
        "account": "12345678901234",
        "text": "Hello, this is a test speech.",
        "voice_id": 12345,
        "async": true
    },
    "response": {
        "title": "Hello, this is a test speech.",
        "mp3_url": "https://...mp3",
        "duration_milliseconds": 5000,
        "state": 3
    }
}
```

**Job still processing:**

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "prompt": "Upbeat electronic dance track",
        "async": true
    }
}
```

**Job failed:**

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create",
    "jobType": "music",
    "status": "failed",
    "created": "2026-01-20T12:34:56.789Z",
    "updated": "2026-01-20T12:35:10.000Z",
    "request": {
        "account": "12345678901234",
        "prompt": "Test prompt",
        "async": true
    },
    "error": "Content policy violation",
    "code": 400
}
```

**400**
**400 Bad Request**

Invalid job ID format.

```json
{
  "error": "Invalid job ID: Missing required component"
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**403**
**403 Forbidden**

Job belongs to a different user.

```json
{
  "error": "Unauthorized access to job"
}
```

**404**
**404 Not Found**

Job not found or has expired (jobs are retained for 7 days).

```json
{
  "error": "Job not found"
}
```

##### Model

**Music Job**

Music generation job structure.

```typescript
{
  jobid: string                              // Unique job identifier
  verb: 'music/create' | 'music/create-instrumental' | 'music/create-advanced' | 'music/regenerate' | 'music/extend'
  jobType: 'music'                           // Job type
  status: 'created' | 'completed' | 'failed'
  created: string                            // ISO 8601 creation timestamp
  updated?: string                           // ISO 8601 last update timestamp

  request: {
    account?: string                         // Mureka account ID
    prompt?: string                          // Text prompt (for create endpoints)
    title?: string                           // Song title
    lyrics?: string                          // Lyrics (for create-advanced, extend)
    song_id?: string                         // Source song ID (for extend, regenerate)
    start_milliseconds?: number              // Start position (for regenerate)
    model?: string                           // AI model used
    instrumental_model?: string              // Instrumental model (for create-instrumental)
    ref_id?: string                          // Reference track ID
    vocal_id?: string                        // Vocal library ID
    motif_id?: string                        // Motif ID
    mood?: string                            // Mood tag
    genre?: string                           // Genre tag
    vocal_gender?: string                    // Vocal gender (male, female)
    async?: boolean                          // Fire-and-forget mode
    replyUrl?: string                        // Webhook URL for callbacks
    replyRef?: string                        // Custom reference for callbacks
  }

  response?: {                               // Present when completed
    feed_id: number
    state: number
    songs: Array<{
      song_id: string
      title: string
      version: string
      duration_milliseconds: number
      generate_at: number
      genres: string[]
      moods: string[]
      mp3_url: string
      share_key: string
      cover: string
      share_link: string
    }>
  }

  error?: string                             // Error message (if failed)
  errorDetails?: string                      // Additional error details
  code?: number                              // HTTP status code (if failed)
}
```

**Speech Job**

Speech generation job structure.

```typescript
{
  jobid: string                              // Unique job identifier
  verb: 'speech'                             // Job verb
  jobType: 'tts'                             // Job type
  status: 'created' | 'completed' | 'failed'
  created: string                            // ISO 8601 creation timestamp
  updated?: string                           // ISO 8601 last update timestamp

  request: {
    account?: string                         // Mureka account ID
    title?: string                           // Speech title
    text?: string                            // Text to convert to speech
    voice_id?: number                        // Voice ID
    conversation?: Array<{voice_id: number, text: string}>  // Multi-speaker conversation
    async?: boolean                          // Fire-and-forget mode
    replyUrl?: string                        // Webhook URL for callbacks
    replyRef?: string                        // Custom reference for callbacks
  }

  response?: {                               // Present when completed
    title: string
    preview: string
    cover: string
    mp3_url: string
    id: number
    duration_milliseconds: number
    audio_quality: number
    state: number
  }

  error?: string                             // Error message (if failed)
  errorDetails?: string                      // Additional error details
  code?: number                              // HTTP status code (if failed)
}
```

##### Examples

**Curl**
```bash
# Get job status
curl "https://api.useapi.net/v1/mureka/jobs/j0121061432017475905m-u777-a12345678901234-bot:mureka" \
  -H "Authorization: Bearer {API token}"

# Poll for completion (check every 5 seconds)
while true; do
  STATUS=$(curl -s "https://api.useapi.net/v1/mureka/jobs/j0121061432017475905m-u777-a12345678901234-bot:mureka" \
    -H "Authorization: Bearer {API token}" | jq -r '.status')

  echo "Status: $STATUS"

  if [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]]; then
    break
  fi

  sleep 5
done
```

**JavaScript**
```javascript
const token = "API token";
const jobid = "j0121061432017475905m-u777-a12345678901234-bot:mureka";

// Get job status
async function getJobStatus(jobid) {
  const response = await fetch(`https://api.useapi.net/v1/mureka/jobs/${jobid}`, {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return await response.json();
}

// Poll until completion
async function waitForCompletion(jobid, intervalMs = 5000) {
  while (true) {
    const job = await getJobStatus(jobid);
    console.log(`Status: ${job.status}`);

    if (job.status === "completed") {
      console.log("Job completed!", job.response);
      return job;
    }

    if (job.status === "failed") {
      console.error("Job failed:", job.error);
      throw new Error(job.error);
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }
}

// Usage
const job = await waitForCompletion(jobid);

// Access song URLs (for music jobs)
if (job.jobType === "music" && job.response?.songs) {
  job.response.songs.forEach((song, i) => {
    console.log(`Song ${i + 1}: ${song.mp3_url}`);
  });
}

// Access audio URL (for speech jobs)
if (job.jobType === "tts" && job.response?.mp3_url) {
  console.log(`Speech audio: ${job.response.mp3_url}`);
}
```

**Python**
```python
import requests
import time

token = "API token"
jobid = "j0121061432017475905m-u777-a12345678901234-bot:mureka"

# Get job status
def get_job_status(jobid: str) -> dict:
    response = requests.get(
        f"https://api.useapi.net/v1/mureka/jobs/{jobid}",
        headers={"Authorization": f"Bearer {token}"}
    )
    response.raise_for_status()
    return response.json()

# Poll until completion
def wait_for_completion(jobid: str, interval_sec: int = 5) -> dict:
    while True:
        job = get_job_status(jobid)
        print(f"Status: {job['status']}")

        if job["status"] == "completed":
            print("Job completed!", job["response"])
            return job

        if job["status"] == "failed":
            raise Exception(f"Job failed: {job.get('error')}")

        time.sleep(interval_sec)

# Usage
job = wait_for_completion(jobid)

# Access song URLs (for music jobs)
if job["jobType"] == "music" and job.get("response", {}).get("songs"):
    for i, song in enumerate(job["response"]["songs"]):
        print(f"Song {i + 1}: {song['mp3_url']}")

# Access audio URL (for speech jobs)
if job["jobType"] == "tts" and job.get("response", {}).get("mp3_url"):
    print(f"Speech audio: {job['response']['mp3_url']}")
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs
## List Running Jobs
<small>January 21, 2026</small>

---

Retrieve a summary of all currently running jobs for your user account. This endpoint is useful for monitoring active music and speech generation jobs across all your configured Mureka accounts.

Jobs are retained for 7 days after creation. Running jobs are tracked separately and show real-time elapsed time.
> **https://api.useapi.net/v1/mureka/jobs**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Responses

**200**
**200 OK**

Returns summary of running jobs grouped by account.

```json
{
    "total": 3,
    "music": 2,
    "tts": 1,
    "accounts": {
        "12345678901234": {
            "total": 3,
            "music": 2,
            "tts": 1,
            "jobs": [
                {
                    "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka",
                    "verb": "speech",
                    "elapsed": "00:00"
                },
                {
                    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
                    "verb": "music/create",
                    "elapsed": "00:24"
                },
                {
                    "jobid": "j0121061447693272611m-u777-a12345678901234-bot:mureka",
                    "verb": "music/create-advanced",
                    "elapsed": "00:09"
                }
            ]
        }
    },
    "availableAccounts": [
        "98765432109876",
        "12345678901234"
    ]
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model

```typescript
{
  total: number                          // Total number of running jobs
  music: number                          // Number of music generation jobs
  tts: number                            // Number of speech (TTS) jobs
  accounts: {
    [accountId: string]: {
      total: number                      // Jobs for this account
      music: number                      // Music jobs for this account
      tts: number                        // TTS jobs for this account
      jobs: Array<{
        jobid: string                    // Unique job identifier
        verb: 'music/create' | 'music/create-instrumental' | 'music/create-advanced' | 'music/regenerate' | 'music/extend' | 'speech'
        elapsed: string                  // Human-readable elapsed time (e.g., "45s", "1m 23s")
      }>
    }
  }
  availableAccounts: string[]            // List of configured account IDs
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/jobs" \
  -H "Authorization: Bearer {API token}"
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/mureka/jobs";

const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`
  }
});

const result = await response.json();
console.log("Running jobs:", result.total);
console.log("Music jobs:", result.music);
console.log("TTS jobs:", result.tts);

// Check jobs per account
for (const [accountId, data] of Object.entries(result.accounts)) {
  console.log(`Account ${accountId}: ${data.total} jobs`);
  data.jobs.forEach(job => {
    console.log(`  - ${job.jobid} (${job.verb}) running for ${job.elapsed}`);
  });
}
```

**Python**
``` python
import requests

token = "API token"
api_url = "https://api.useapi.net/v1/mureka/jobs"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(api_url, headers=headers)
result = response.json()

print(f"Running jobs: {result['total']}")
print(f"Music jobs: {result['music']}")
print(f"TTS jobs: {result['tts']}")

# Check jobs per account
for account_id, data in result['accounts'].items():
    print(f"Account {account_id}: {data['total']} jobs")
    for job in data['jobs']:
        print(f"  - {job['jobid']} ({job['verb']}) running for {job['elapsed']}")
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-moods-and-genres ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-moods-and-genres
## Retrieve a list of supported Genres, Moods and Vocals
<small>December 2, 2024</small>

---
> **https://api.useapi.net/v1/mureka/music/moods-and-genres/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "genres": [
        {
            "tag": "pop",
            "cover": "cos-prod/res/image/Pop@4x.png"
        },
        {
            "tag": "<genre 2>",
            "cover": "<cover image 1>"
        },
        {
            "tag": "<genre NN>",
            "cover": "<cover image NN>"
        }
    ],
    "moods": [
        {
            "tag": "relaxed"
        },
        {
            "tag": "<mood 2>"
        },
        {
            "tag": "<mood NN>"
        }
    ],
    "vocals": [
        {
            "tag": "female vocal"
        },
        {
            "tag": "male vocal"
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    genres: { tag: string, cover?: string }[]
    moods: { tag: string }[]
    vocals: { tag: string }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/music/moods-and-genres/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/moods-and-genres/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/music/moods-and-genres/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-refs ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-refs
## Retrieve a list of reference songs
<small>December 2, 2024</small>

---
> **https://api.useapi.net/v1/mureka/music/refs/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  
 
- `mood` is optional. Filter songs by mood, to retrieve list supported moods use [GET music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres).

- `genre` is optional. Filter songs by genre, to retrieve list supported genres use [GET music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres).

- `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`. 

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "id": 1122334455,
            "url": "https://<song download url>.mp3",
            "duration_milliseconds": 30000,
            "mood": "relaxed",
            "title": "<song title>",
            "genre": "afrobeat",
            "username": "<user name>"
        },
        {
            "id": 66778899,
            "url": "https://<song download url>.mp3",
            "duration_milliseconds": 30000,
            "mood": "restless",
            "title": "<song title>",
            "genre": "rock",
            "username": "<user name>"
        }
    ],
    "last_id": 77665544332211,
    "more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        id: number
        url: string
        duration_milliseconds: number
        mood: string
        title: string
        genre: string
        username: string
    }[]
    last_id: number
    more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/music/refs/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/refs/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/music/refs/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-song_id ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-song_id
## Retrieve generated song lyrics and other details
<small>December 2, 2024 (March 31, 2025)</small>

---
> **https://api.useapi.net/v1/mureka/music/`song_id`**

The `song_id` value returned by one of the following endpoints: 
* [GET /music](/docs/api-mureka-v1/get-mureka-music)
* [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
* [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
* [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)   

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  

```json
{
    "song": {
        "song_id": "user:777-mureka:987654321-song:123456789",
        "title": "<song title>",
        "version": "1",
        "duration_milliseconds": 1234567,
        "generate_at": 123456789,
        "genres": [
            "rock",
            "metal"
        ],
        "moods": [
            "majestic",
            "romantic",
            "mysterious"
        ],
        "mp3_url": "https://<download link>.mp3",
        "share_key": "<share key>",
        "machine_audit_state": 1,
        "credit_type": 1,
        "cover": "https://<cover image>.png",
        "lyrics": [
            {
                "rows": [
                    {
                        "start": 1,
                        "end": 100,
                        "text": "lyrics here"
                    },
                    {
                        "start": 200,
                        "end": 300,
                        "text": "lyrics continues"
                    }
                ]
            }
        ],
        "video": {},
        "share_link": "https://<share link>"
    },
    "user": {
        "id": "987654321",
        "user_id": 987654321,
        "stage_name": "<stage name>",
        "profile_image": "https://<profile image>.png"
    },
    "feed_id": 998877665544332211,
    "conn_id": "…",
    "state": 3,
    "generation_method": 1,
    "model": "O1"    
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "The song has been deleted"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    song: {
        song_id: number
        title: string
        version: string
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        share_link: string
        machine_audit_state: number
        credit_type: number
        cover: string
        lyrics: {
            seg_type: number
            user_input_tag: string
            start?: number
            end?: number
            rows?: {
                start?: number
                end?: number
                text: string
            }[]
        }[]
        video?: {
            video_url: string
            video_cover_url: string
            video_id: number
        }
    }
    user: {
        id: string
        user_id: number
        stage_name: string
        profile_image: string
    }
    feed_id: number
    conn_id: string
    state: number
    generation_method: number
    model: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/music/song_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const song_id = "song_id"; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/${song_id}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
song_id = "song_id"
apiUrl = f"https://api.useapi.net/v1/mureka/music/{song_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-vocals ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-vocals
## Retrieve a list of vocal samples including the ones you uploaded
<small>December 2, 2024 (January 15, 2025)</small>

---
> **https://api.useapi.net/v1/mureka/music/vocals/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`.  

- `mine` is optional. Set to `true` to retrieve list of vocals uploaded via [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal).  
  Supported values: `true`, `false` (default).

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "id": 47235584950273,
            "url": "https://...mp3",
            "duration_milliseconds": 40731,
            "gender": 2,
            "title": "James",
            "created_at": 1735202082,
            "username": "Star_Boy",
            "background_url": "https://...jpg"
        },
        {
            "id": 48696156946433,
            "url": "https://...mp3",
            "duration_milliseconds": 49059,
            "gender": 2,
            "title": "Bella",
            "created_at": 1735898537,
            "username": "ZenZephyr",
            "background_url": "https://...jpeg"
        }
    ],
    "last_id": 1726311196088,
    "more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        id: number
        url: string
        duration_milliseconds: number
        gender: number
        title: string
        created_at: number
        username: string
        background_url: string
    }[]
    last_id: number
    more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/music/vocals/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/vocals/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/music/vocals/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music
## Retrieve generated music
<small>December 2, 2024 (March 31, 2025)</small>

---
> **https://api.useapi.net/v1/mureka/music/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`.  
  
- `expand` is optiona. Set it to `true` if you want to retrieve complete song details.  
  Supported values: `true`, `false` (default).

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "feed_id": 111222333,
            "state": 3,
            "songs": [
                {
                    "song_id": "user:777-mureka:123456789-song:111122222",
                    "title": "<song title>",
                    "version": "1",
                    "duration_milliseconds": 123456,
                    "generate_at": 123456789,
                    "genres": [
                        "rock",
                        "metal"
                    ],
                    "moods": [
                        "majestic",
                        "romantic",
                        "mysterious"
                    ],
                    "mp3_url": "https://<download link>.mp3",
                    "share_key": "<share key>",
                    "machine_audit_state": 1,
                    "credit_type": 1,
                    "cover": "https://<cover image>.png",
                    "share_link": "https://<share link>"
                },
                {
                    "song_id": "user:777-mureka:123456789-song:33334444",
                    "title": "<song title>",
                    "version": "1",
                    "duration_milliseconds": 223456,
                    "generate_at": 223456789,
                    "genres": [
                        "rock",
                        "metal"
                    ],
                    "moods": [
                        "quirky",
                        "relaxed",
                        "mysterious"
                    ],
                    "mp3_url": "https://<download link>.mp3",
                    "share_key": "<share key>",
                    "machine_audit_state": 1,
                    "credit_type": 1,
                    "cover": "https://<cover image>.png",
                    "share_link": "https://<share link>"
                }
            ],
            "conn_id": "…",
            "is_accelerated": true,
            "generation_method": 1,
            "model": "V6"
        },
        {
            "feed_id": 444555666,
            "state": 3,
            "songs": [
                {
                    "song_id": "user:777-mureka:123456789-song:55556666",
                    "title": "<song title>",
                    "version": "1",
                    "duration_milliseconds": 123456,
                    "generate_at": 123456789,
                    "genres": [
                        "latin",
                        "world-music"
                    ],
                    "moods": [
                        "calm",
                        "romantic",
                        "happy"
                    ],
                    "mp3_url": "https://<download link>.mp3",
                    "share_key": "<share key>",
                    "machine_audit_state": 1,
                    "credit_type": 1,
                    "cover": "https://<cover image>.png",
                    "share_link": "https://<share link>"
                },
                {
                    "song_id": "user:777-mureka:123456789-song:77778888",
                    "title": "<song title>",
                    "version": "1",
                    "duration_milliseconds": 223456,
                    "generate_at": 223456789,
                    "genres": [
                        "pop",
                        "indie"
                    ],
                    "moods": [
                        "majestic",
                        "inspired",
                        "quirky"
                    ],
                    "mp3_url": "https://<download link>.mp3",
                    "share_key": "<share key>",
                    "machine_audit_state": 1,
                    "credit_type": 1,
                    "cover": "https://<cover image>.png",
                    "share_link": "https://<share link>"
                }
            ],
            "conn_id": "…",
            "is_accelerated": true,
            "generation_method": 1,
            "model": "O1"
        }
    ],
    "last_id": 123456789,
    "more": true,
    "total": 9623
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        feed_id: number
        state: number
        songs: {
            song_id: number
            title: string
            version: string
            duration_milliseconds: number
            generate_at: number
            genres: string[]
            moods: string[]
            mp3_url: string
            share_key: string
            share_link: string
            machine_audit_state: number
            wave_list: number[]
            credit_type: number
            cover: string
            is_played?: boolean
            is_liked?: boolean
            video?: {
                video_url: string
                video_cover_url: string
                video_id: number
            }
        }[]
        is_accelerated: boolean
        conn_id: string
        generation_method: number
        model: string
    }[]
    last_id: number
    total: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/music/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/music/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile
## Retrieve your [mureka.ai](https://www.mureka.ai) account information and remaining credits
<small>December 2, 2024 (April 4, 2026)</small>

---
> **https://api.useapi.net/v1/mureka/profile/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "user": {
        "id": "987654321",
        "user_id": 987654321,
        "stage_name": "useapi.net",
        "profile_image": "https://static-cos.mureka.ai/cos-prod/image/default.png",
        "is_vip": true,
        "vip_level": 2,
        "created_on": 1756353867,
        "sid": 123456789,
        "last_active_time": 1771038894,
        "country_code": "US",
        "register_ip": "192.168.0.1",
        "vip_end": 1771632412,
        "vip_name": "Monthly Pro",
        "vip_level_name": "basic",
        "vip_period_name": "month",
        "created_on_UTC": "2025-08-28T04:04:27.000Z",
        "vip_end_UTC": "2026-02-21T00:06:52.000Z"
    },
    "country_code": "US",
    "credits": 500,
    "feed_list_count": 574,
    "credits_silver": 4,
    "free_download_mp3_models": [
        "V8"
    ],
    "models": {
        "official_models": [
            {
                "display_name": "V9",
                "model": "mureka-9",
                "description": "Advanced prompt control, studio-grade sound",
                "generation_amount": 1,
                "required_credits": 12,
                "supported_control_types": [
                    "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix"
                ],
                "show_free_to_use": true,
                "app_display_name": "V9",
                "min_tier": "basic"
            },
            {
                "display_name": "V8",
                "model": "mureka-8.0.1",
                "description": "Publish-ready music, emotional vocals, memorable melodies.",
                "generation_amount": 1,
                "required_credits": 12,
                "supported_control_types": [
                    "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix"
                ],
                "show_free_to_use": true,
                "app_display_name": "V8",
                "min_tier": "basic"
            },
            {
                "display_name": "O2",
                "model": "mureka-o2",
                "description": "All-in-one smart music model, professional results.",
                "generation_amount": 1,
                "required_credits": 20,
                "supported_control_types": [
                    "refer", "prompt", "soundtrack", "instrumental", "vocal"
                ],
                "show_free_to_use": true,
                "app_display_name": "O2",
                "min_tier": "basic"
            },
            {
                "display_name": "V7.6",
                "model": "mureka-7.6",
                "description": "Pro music creation, finer prompt control.",
                "generation_amount": 1,
                "required_credits": 10,
                "supported_control_types": [
                    "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental"
                ],
                "show_free_to_use": true,
                "app_display_name": "V7.6",
                "min_tier": "basic"
            },
            {
                "display_name": "V7.5-all",
                "model": "mureka-7.5all",
                "description": "Easy music creation, clear vocal, quick mixing, entry-level.",
                "generation_amount": 1,
                "required_credits": 10,
                "supported_control_types": [
                    "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental"
                ],
                "show_free_to_use": true,
                "app_display_name": "V7.5-all"
            }
        ],
        "default_model": {
            "display_name": "V9",
            "model": "mureka-9",
            "description": "Advanced prompt control, studio-grade sound",
            "generation_amount": 1,
            "required_credits": 12,
            "supported_control_types": [
                "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix"
            ],
            "show_free_to_use": true,
            "app_display_name": "V9",
            "min_tier": "basic"
        }
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    user: {
        id: string
        user_id: number
        stage_name: string
        profile_image: string
        is_vip: boolean
        vip_level: number
        created_on: number
        sid: number
        register_ip: string
        vip_start: number
        vip_end: number
        vip_name: string
        vip_level_name: string
        vip_period_name: string
    }
    credits: number
    credits_silver?: number
    feed_list_count: number
    free_download_mp3_models?: string[]
    models?: {
        official_models: {
            display_name: string
            model: string
            description?: string
            generation_amount?: number
            required_credits: number
            supported_control_types: string[]
            show_free_to_use?: boolean
            app_display_name?: string
            min_tier?: string
        }[]
        default_model: {
            display_name: string
            model: string
            description?: string
            generation_amount?: number
            required_credits: number
            supported_control_types: string[]
            show_free_to_use?: boolean
            app_display_name?: string
            min_tier?: string
        }
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/profile/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/profile/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/mureka/profile/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices
## Retrieve speech voices
<small>August 18, 2025</small>

---

This endpoint retrieves available voices for speech generation, including both built-in voices and your custom cloned voices. Use the `cloned` parameter to filter for only cloned voices created via [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice). Use pagination with the `last_id` parameter and `more` field to browse through all available voices. Voices include preview audio for testing before use.
> **https://api.useapi.net/v1/mureka/speech/voices/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `last_id` is optional. Use it to retrieve the next page of data.  
  Set its value to the `last_id` returned in the previous response.

- `cloned` is optional. Filter voices by type.  
  Set to `true` for only cloned voices, `false` for built-in voices, or omit for all voices.  
  Supported values: `true`, `false`.

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "id": 12345678901234,
            "user_id": 23456789012345,
            "title": "Sarah",
            "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
            "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
            "language": "en",
            "created_at": 1755483687,
            "description": "Professional female voice",
            "duration_milliseconds": 12520,
            "source_type": 2,
            "machine_audit_state": 1
        },
        {
            "id": 34567890123456,
            "user_id": 23456789012345,
            "title": "Michael",
            "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
            "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
            "language": "en",
            "created_at": 1755483619,
            "description": "Deep male narrator",
            "duration_milliseconds": 13680,
            "source_type": 2,
            "machine_audit_state": 1
        }
    ],
    "last_id": 1755483619964    
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        id: number
        user_id: number
        title: string
        cover: string
        mp3_url: string
        language: string
        created_at: number
        description: string
        duration_milliseconds: number
        source_type?: number
        machine_audit_state: number
    }[]
    last_id: number
    more?: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech
## Retrieve generated speech
<small>August 18, 2025</small>

---

This endpoint retrieves a list of previously generated speech recordings from your Mureka account. Use pagination with the `last_id` parameter to browse through all your speech history. The `more` field indicates whether additional pages are available. Each response includes the generated audio URLs, titles, and metadata for easy playback and management.
> **https://api.useapi.net/v1/mureka/speech/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `last_id` is optional. Use it to retrieve the next page of data.  
  Set its value to the `last_id` returned in the previous response.  

##### Responses 

**200**
**200 OK**  

```json
{
    "list": [
        {
            "title": "Morning Conversation",
            "preview": "Good morning! How are you doing today? I hope you're having a wonderful start to your day.",
            "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
            "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
            "id": 23456789012345,
            "duration_milliseconds": 8500,
            "audio_quality": 2,
            "state": 3
        },
        {
            "title": "Evening Reflection",
            "preview": "As the day comes to an end, let's take a moment to reflect on all the good things that happened.",
            "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
            "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
            "id": 34567890123456,
            "duration_milliseconds": 12300,
            "audio_quality": 2,
            "state": 3
        }
    ],
    "last_id": 1755483687,
    "more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    list: {
        title: string
        preview: string
        cover: string
        mp3_url: string
        id: number
        duration_milliseconds: number
        audio_quality: number
        state: number
    }[]
    last_id: number
    more?: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/speech/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/mureka/speech/"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/mureka/speech/"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts-account ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts-account
## Create or update Mureka API account configuration (Legacy)
<small>December 2, 2024 (January 20, 2026)</small>

---
> This is the legacy method that requires manual token renewal every 30 days. We recommend using [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) with Google cookies for **automatic token refresh**.

See [Setup Mureka (Legacy)](/docs/start-here/setup-mureka-legacy) for details.     
> **https://api.useapi.net/v1/mureka/accounts/`account`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Mureka account",
    "token": "Mureka token",
}
```
- `account` and `token` are **required**. Please see [Setup Mureka](/docs/start-here/setup-mureka) for details. 

- `account` value specified in the request body **must match** the account value specified in the URL path <small>https://api.useapi.net/v1/mureka/accounts/`account`</small>.

##### Responses 

**201**
**201 Created** 

```json
{
    "updated": 1724514995,
    "account": "123456789",
    "token": "<token>",
    "updatedUTC": "2024-10-24T15:56:35.000Z",
    "email": "user@gmail.com"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  account: string
  token: string
  updated: number
  updatedUTC: string
  email?: string
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/accounts/<account> \
     -d '{"account": "…", "token": "…"}'
```

**JavaScript**
``` javascript
const account = "Mureka account";      
const token = "Mureka token";      
const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${account}`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, token
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Mureka account"
token = "Mureka token"
apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{account}" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "token": f"{token}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts
## Configure Mureka API account with auto-refresh
<small>January 19, 2026 (January 20, 2026)</small>

---

Configure your Mureka account for API access using Google OAuth cookies. This method enables **automatic token refresh** - when your Mureka session expires, the API will automatically refresh it using Google One Tap authentication.

See [Setup Mureka](/docs/start-here/setup-mureka) for detailed instructions.
> Looking for the [legacy method](/docs/api-mureka-v1/post-mureka-accounts-account) with manual token setup?
> **https://api.useapi.net/v1/mureka/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body

**Option 1: Tab-separated format** (paste cookie as copied from DevTools)
```
{
    "sessionCookie": "__Secure-3PSID<TAB>g.a0...secured...076<TAB>.google.com<TAB>/<TAB>2027-02-23T04:38:16.033Z<TAB>167<TAB>✓<TAB>✓<TAB>None<TAB><TAB><TAB>High"
}
```
Where `<TAB>` represents actual tab characters as copied from Chrome DevTools.

**Option 2: Minimal JSON format**
```json
{
    "sessionCookie": {"value": "g.a0...secured...076", "expires": "2027-02-23T04:38:16.033Z"}
}
```

- `sessionCookie` is **required**. The `__Secure-3PSID` cookie from `accounts.google.com`. Accepts:
  - Tab-separated format (copied directly from Chrome DevTools)
  - Minimal JSON: `{"value": "g.a0...secured...076", "expires": "2027-02-23T04:38:16.033Z"}`
  - Full JSON cookie object

##### Responses

**200**
**200 OK**

Account configured successfully with auto-refresh enabled.

```json
{
    "64532357578753": {
        "account": "64532357578753",
        "token": "JfE...secured...2sWc",
        "hasAutoRefresh": true,
        "tokenIssuedDaysAgo": 0,
        "updatedUTC": "2026-01-19T04:38:16.000Z",
        "email": "user@gmail.com",
        "sessionCookie": {
            "name": "__Secure-3PSID",
            "value": "g.a0005wi...secured...90076",
            "domain": ".google.com",
            "path": "/",
            "expires": "2027-02-23T04:38:16.033Z",
            "httpOnly": true,
            "secure": true,
            "sameSite": "None",
            "added": "2026-01-19T04:38:16.000Z"
        },
        "user": {
            "id": "64532357578753",
            "name": "User",
            "avatar": "https://...",
            "gold": 40,
            "vip_type": 2
        }
    }
}
```

**400**
**400 Bad Request**

Cookie validation failed or expired.

```json
{
  "error": "Google cookie expired on 2025-01-19T04:38:16.033Z. Please provide a fresh cookie.",
  "code": 597
}
```

Or if the cookie is not found:
```json
{
  "error": "Required cookie __Secure-3PSID not found in sessionCookie",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  [account: string]: {
    account: string
    token: string
    hasAutoRefresh: boolean
    tokenIssuedDaysAgo: number
    updatedUTC: string
    email?: string
    sessionCookie: {
      name: string
      value: string
      domain: string
      path: string
      expires: string
      httpOnly: boolean
      secure: boolean
      sameSite: string
      added: string
    }
    user: {
      id: string
      name: string
      avatar: string
      gold: number
      vip_type: number
    }
  }
  error: string
  code: number
}
```

##### Automatic Token Refresh

When configured with this endpoint, your Mureka account benefits from **automatic token refresh**:

- The `__Secure-3PSID` Google cookie is valid for approximately **13 months**
- When your Mureka session token expires (typically after 30 days), the API **automatically** refreshes it using Google One Tap
- You will receive email notifications when:
  - A token refresh is initiated
  - The refresh succeeds
  - The refresh fails (manual re-setup required)

If automatic refresh fails (e.g., Google invalidated the cookie), you will need to repeat the [setup process](/docs/start-here/setup-mureka) with fresh cookies.

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/accounts \
     -d '{"sessionCookie": {"value": "g.a0...YOUR_COOKIE_VALUE...076", "expires": "2027-02-23T04:38:16.033Z"}}'
```

**JavaScript**
``` javascript
const apiUrl = 'https://api.useapi.net/v1/mureka/accounts';
const api_token = "API token";
// Option 1: Tab-separated format (paste directly from DevTools)
// const sessionCookie = "paste tab-separated cookie row from DevTools here";
// Option 2: Minimal JSON format
const sessionCookie = {value: "g.a0...secured...076", expires: "2027-02-23T04:38:16.033Z"};

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ sessionCookie })
});

const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests

apiUrl = "https://api.useapi.net/v1/mureka/accounts"
api_token = "API token"
# Option 1: Tab-separated format (paste directly from DevTools)
# sessionCookie = "paste tab-separated cookie row from DevTools here"
# Option 2: Minimal JSON format
sessionCookie = {"value": "g.a0...secured...076", "expires": "2027-02-23T04:38:16.033Z"}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_token}"
}
body = {
    "sessionCookie": sessionCookie
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-motif ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-motif

## Upload mp3 melody (motif) track 
<small>December 13, 2024</small>

---

Upload mp3 audio file up to 5GB in size. Use `id` value to reference uploaded melody when using the parameter `motif_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). Uploaded file will not be visible for other users of the Mureka.ai

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/mureka/files/motif/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/mpeg 
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

The response contains an `id` that you can use to reference the uploaded melody when using the parameter `motif_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced).

```json
{
  "id": "user:777-mureka:987654321-file:123456789",
  "url": "https://<song download url>.mp3",
  "duration_milliseconds": 50000
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: string
  url: string
  duration_milliseconds: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/files/motif/?account=<account>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary /path/to/your/audio.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/motif/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3";
    const response = await fetch(url);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const fileName = "./music.mp3";
    blob = new Blob([await fsp.readFile(fileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="music-file" type="file"> 
    const musicFile = document.getElementById(`music-file`);
    if (musicFile.files[0])
        blob = musicFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account account"
apiUrl = f"https://api.useapi.net/v1/mureka/files/motif/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3"
# response_audio = requests.get(url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
# audio_file_path = "./audio.mp3"
# with open(audio_file_path, 'rb') as audio_file:
#     file_content = audio_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-vocal ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-vocal

## Upload mp3 vocal
<small>January 15, 2025</small>

---

Upload mp3 audio file up to 5GB in size. Use `id` value to reference uploaded vocal when using the parameter `vocal_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). Uploaded file will not be visible for other users of the Mureka.ai

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/mureka/files/vocal/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/mpeg 
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.
    
- `title` is **required**. Provide name for your vocal.

##### Responses 

**200**
**200 OK**  

The response contains an `id` that you can use to reference the uploaded melody when using the parameter `vocal_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced).

```json
{
  "id": 1234567890,
  "title": "vocal name",
  "url": "https://<vocal download url>.mp3",
  "duration_milliseconds": 50000
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: number
  title: string
  url: string
  duration_milliseconds: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/files/vocal/?account=<account>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary /path/to/your/audio.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account account"; 
const apiUrl = `https://api.useapi.net/v1/mureka/files/vocal/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3";
    const response = await fetch(url);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const fileName = "./music.mp3";
    blob = new Blob([await fsp.readFile(fileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="music-file" type="file"> 
    const musicFile = document.getElementById(`music-file`);
    if (musicFile.files[0])
        blob = musicFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account account"
apiUrl = f"https://api.useapi.net/v1/mureka/files/vocal/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3"
# response_audio = requests.get(url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
# audio_file_path = "./audio.mp3"
# with open(audio_file_path, 'rb') as audio_file:
#     file_content = audio_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files
## Upload mp3 audio track to your music collection
<small>December 13, 2024</small>

---

Upload mp3 audio file up to 5GB in size. Files uploaded using this endpoint will be visible to all users of Mureka.ai website. To retrieve a full list of all your uploaded tracks use [GET /files](/docs/api-mureka-v1/get-mureka-files).

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/mureka/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/mpeg 
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `title` is **required**. 

- `genre` is **required**. Provide the genre of your track. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres).

- `mood` is **required**. Provide the mood of your track. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres).

- `url` is optional. Provide the original YouTube url if applicable.

##### Responses 

**200**
**200 OK**  

The response contains an `id` that you can use to reference the uploaded audio file when using the parameter `ref_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced).

```json
{
  "id": 1122334455,
  "url": "https://<song download url>.mp3",
  "duration_milliseconds": 30000,
  "mood": "relaxed",
  "title": "<song title>",
  "genre": "afrobeat"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: number
  url: string
  duration_milliseconds: number
  mood: string
  title: string
  genre: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/files/?account=<account>&title=<title>&genre=<genre>&mood=<mood>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary /path/to/your/audio.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account account"; 
const title = "song title";
const mood = "song mood";
const genre = "song genre";
const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}&title=${title}&genre=${genre}&mood=${mood}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3";
    const response = await fetch(url);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const fileName = "./music.mp3";
    blob = new Blob([await fsp.readFile(fileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="music-file" type="file"> 
    const musicFile = document.getElementById(`music-file`);
    if (musicFile.files[0])
        blob = musicFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account account"
title = "song title"
mood = "song mood"
genre = "song genre"
apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}&title={title}&genre={genre}&mood={mood}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3"
# response_audio = requests.get(url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
# audio_file_path = "./audio.mp3"
# with open(audio_file_path, 'rb') as audio_file:
#     file_content = audio_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-advanced ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-advanced
## Create a song using custom lyrics, styles, vocals and reference song 
<small>December 2, 2024 (April 4, 2026)</small>

---

Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your lyrics.
> **https://api.useapi.net/v1/mureka/music/create-advanced**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional Mureka API account",
    "lyrics": "Required song lyrics",
    "title": "Optional song title",
}
```

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or if the `motif_id` parameter is provided. However, if you have multiple accounts configured and the `motif_id` parameter is not provided, this parameter becomes **required**.  

- `lyrics` is **required**. Lyrics for the song.  
  Maximum length: 5000 characters.

- `title` is optional. Song title.  
  Maximum length: 50 characters.

- `desc` is optional. To guide song generation, provide a comma-separated list of genres, moods, and desired vocals. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). This parameter is not compatible with parameters `ref_id`, `vocal_id` or `motif_id`.
  Example: `pop, electronic, happy, female vocal`"
  Maximum length: 1000 characters.

- `vocal_id` is optional. Specify the desired vocal. See supported vocals using [GET /music/vocals](/docs/api-mureka-v1/get-mureka-music-vocals).  
  
- `ref_id` is optional. Create songs inspired by a reference track. See available tracks using [GET /music/refs](/docs/api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](/docs/api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](/docs/api-mureka-v1/get-mureka-files).

- `motif_id` is optional. Create songs inspired by a melody idea to kickstart your song. Upload the melody using [POST /files/motif](/docs/api-mureka-v1/post-mureka-files-motif) and use the returned `id` value. This parameter is not compatible with parameters `ref_id`, `vocal_id` or `desc`.    

- `model` is optional.
  Supported values: `V9` (default), `V8`, `O2`, `V7.6`, `V7.5`.

- `vocal_gender` is optional. Specify desired vocal gender.
  Supported values: `female`, `male`.

Note: `V7`, `O1`, `V6`, and `V5.5` are retired models that now redirect to `V7.6`.

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK**

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "feed_id": 11223344,
    "state": 3,
    "songs": [
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1",
            "duration_milliseconds": 234567,
            "generate_at": 12345677,
            "genres": [
                "electronic",
                "indie"
            ],
            "moods": [
                "quirky",
                "angry",
                "restless"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "recall": true,
            "machine_audit_state": 4,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        },
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "2",
            "duration_milliseconds": 1234567,
            "generate_at": 12345667,
            "genres": [
                "electronic",
                "world-music"
            ],
            "moods": [
                "dark",
                "quirky",
                "energetic"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        }
    ]
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create-advanced",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "lyrics": "Your song lyrics here",
        "title": "My Song",
        "model": "V7.6",
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.   
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Music generation completed. Returns full song data with MP3 URLs.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    feed_id: number
    state: number
    songs?: {
        song_id: string
        title: string
        version: string
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        machine_audit_state: number
        credit_type: number
        cover: string
        share_link: string
    }[]
    error?: string
    code?: number
    msg?: string
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'music/create-advanced'              // Job verb
    jobType: 'music'                           // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        lyrics: string
        title?: string
        desc?: string
        vocal_id?: string
        ref_id?: string
        motif_id?: string
        model?: string
        vocal_gender?: string
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    msg?: string                               // Additional error message
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/create-advanced \
     -d '{"account": "…", "lyrics": "…"}'
```

**JavaScript**
``` javascript
const account = "Mureka account";      
const lyrics = "<Your song lyrics here>";      
const apiUrl = `https://api.useapi.net/v1/mureka/music/create-advanced`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, lyrics
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Mureka account"
lyrics = "<Your song lyrics here>"
apiUrl = f"https://api.useapi.net/v1/mureka/music/create-advanced" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "lyrics": f"{lyrics}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-instrumental ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-instrumental
## Create instrumental music
<small>March 31, 2025 (April 4, 2026)</small>

---

Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your prompt.
> **https://api.useapi.net/v1/mureka/music/create-instrumental**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional Mureka API account",
    "prompt": "Ambient electronic with soft pads, great for nature walks and peaceful moments."
}
```

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or if the `motif_id` parameter is provided. However, if you have multiple accounts configured and the `motif_id` parameter is not provided, this parameter becomes **required**.  

- `prompt` is optional. Describe your instrumental music.    
  Maximum length: 1000 characters.

- `title` is optional. Song title.  
  Maximum length: 50 characters.

- `ref_id` is optional. Create music inspired by a reference track. See available tracks using [GET /music/refs](/docs/api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](/docs/api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](/docs/api-mureka-v1/get-mureka-files).

- `model` is optional.
  Supported values: `V9` (default), `V8`, `O2`, `V7.6`, `V7.5`.

  Note: `V7`, `O1`, `V6`, and `V5.5` are retired models that now redirect to `V7.6`.

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK** 

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "feed_id": 11223344,
    "state": 3,
    "songs": [
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1",
            "duration_milliseconds": 234567,
            "generate_at": 12345677,
            "genres": [
                "electronic",
                "indie"
            ],
            "moods": [
                "quirky",
                "angry",
                "restless"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "recall": true,
            "machine_audit_state": 4,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        },
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "2",
            "duration_milliseconds": 1234567,
            "generate_at": 12345667,
            "genres": [
                "electronic",
                "world-music"
            ],
            "moods": [
                "dark",
                "quirky",
                "energetic"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        }
    ]
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create-instrumental",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "prompt": "Ambient electronic with soft pads",
        "model": "V7.6",
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.  
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Music generation completed. Returns full song data with MP3 URLs.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    feed_id: number
    state: number
    songs?: {
        song_id: string
        title: string
        version: string
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        machine_audit_state: number
        credit_type: number
        cover: string
        share_link: string
    }[]
    error?: string
    code?: number
    msg?: string
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'music/create-instrumental'                // Job verb
    jobType: 'music'                           // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        prompt?: string
        title?: string
        ref_id?: string
        model?: string
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    msg?: string                               // Additional error message
    rawData?: string                           // Raw error data (if available)
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/create-instrumental \
     -d '{"account": "…", "prompt": "…"}'
```

**JavaScript**
``` javascript
const account = "Mureka account";      
const prompt = "<Your music prompt here>";      
const apiUrl = `https://api.useapi.net/v1/mureka/music/create-instrumental`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Mureka account"
prompt = "<Your music prompt here>"
apiUrl = f"https://api.useapi.net/v1/mureka/music/create-instrumental" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create
## Create a song using AI-generated lyrics based on your prompt
<small>December 2, 2024 (April 4, 2026)</small>

---

Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your lyrics.
> **https://api.useapi.net/v1/mureka/music/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional Mureka API account",
    "prompt": "Optional text prompt"
}
```

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple music configured, this parameter becomes **required**.  

- `prompt` is optional. Use it to guide AI to generate desired lyrics. If omitted AI will generate some random lyrics.  
  Maximum length: 3000 characters.

- `model` is optional.
  Supported values: `V9` (default), `V8`, `O2`, `V7.6`, `V7.5`.

  Note: `V7`, `O1`, `V6`, and `V5.5` are retired models that now redirect to `V7.6`.

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK** 

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "feed_id": 11223344,
    "state": 3,
    "songs": [
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1",
            "duration_milliseconds": 234567,
            "generate_at": 12345677,
            "genres": [
                "electronic",
                "indie"
            ],
            "moods": [
                "quirky",
                "angry",
                "restless"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "recall": true,
            "machine_audit_state": 4,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        },
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "2",
            "duration_milliseconds": 1234567,
            "generate_at": 12345667,
            "genres": [
                "electronic",
                "world-music"
            ],
            "moods": [
                "dark",
                "quirky",
                "energetic"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        }
    ]
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/create",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "prompt": "Silly song about Santa",
        "model": "V7.6",
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Music generation completed. Returns full song data with MP3 URLs.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    feed_id: number
    state: number
    songs?: {
        song_id: string
        title: string
        version: string
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        machine_audit_state: number
        credit_type: number
        cover: string
        share_link: string
    }[]
    error?: string
    code?: number
    msg?: string
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'music/create'                             // Job verb
    jobType: 'music'                           // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        prompt?: string
        model?: string
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    msg?: string                               // Additional error message
    rawData?: string                           // Raw error data (if available)
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/create \
     -d '{"account": "…", "prompt": "…"}'
```

**JavaScript**
``` javascript
const account = "Mureka account";      
const prompt = "Silly song about Santa";      
const apiUrl = `https://api.useapi.net/v1/mureka/music/create`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Mureka account"
prompt = "Silly song about Santa"
apiUrl = f"https://api.useapi.net/v1/mureka/music/create" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-download ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-download
## Download the song license and stems
<small>March 31, 2025</small>

---
> **https://api.useapi.net/v1/mureka/music/download**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "song_id": 123456789,
    "type": "stem"
}
```

- `song_id` is **required**.  
  The `song_id` value returned by one of the following endpoints: 
  * [GET /music](/docs/api-mureka-v1/get-mureka-music)
  * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
  * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)   
  * [POST /music/download](/docs/api-mureka-v1/post-mureka-music-download)
  * [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate)

- `type` is **required**. Supported values: `stem`, `license`
  
##### Responses 

**200**
**200 OK** 

```json
{
    "oss_key": "https://static-cos.mureka.ai/…zip",
    "paid_state": 1
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  oss_key: string
  paid_state: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/download \
     -d '{"song_id": …, "type": "stem"}'
```

**JavaScript**
``` javascript
const song_id = 123456789;      
const type = "stem";   
const apiUrl = `https://api.useapi.net/v1/mureka/music/download`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  song_id, type
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
song_id = 123456789
type = "stem"   
apiUrl = f"https://api.useapi.net/v1/mureka/music/download" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "song_id": song_id,
    "type": f"{type}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-extend ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-extend
## Extend song
<small>December 13, 2024 (January 21, 2026)</small>

---
> **https://api.useapi.net/v1/mureka/music/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "song_id": 123456789,
    "lyrics": "required lyrics to extend your original song"
}
```

- `song_id` is **required**.  
  The `song_id` value returned by one of the following endpoints: 
  * [GET /music](/docs/api-mureka-v1/get-mureka-music)
  * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
  * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)    
  * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend)
  * [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate)

- `lyrics` is **required**. Lyrics for the song extension.
  Maximum length: 3000 characters.

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK** 

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "feed_id": 11223344,
    "state": 3,
    "songs": [
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1...1",
            "is_regenerate": true,
            "regenerate_from": 123456,            
            "duration_milliseconds": 234567,
            "generate_at": 12345677,
            "genres": [
                "electronic",
                "indie"
            ],
            "moods": [
                "quirky",
                "angry",
                "restless"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "recall": true,
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        },
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1...2",
            "is_regenerate": true,
            "regenerate_from": 123456,            
            "duration_milliseconds": 1234567,
            "generate_at": 12345667,
            "genres": [
                "electronic",
                "world-music"
            ],
            "moods": [
                "dark",
                "quirky",
                "energetic"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        }
    ]
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Music extension is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/extend",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "song_id": "user:777-mureka:123456789-song:33445566",
        "lyrics": "New verse lyrics here",
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.  
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Music extension completed. Returns full song data with MP3 URLs.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    feed_id: number
    state: number
    songs?: {
        song_id: string
        title: string
        version: string
        is_regenerate: boolean
        regenerate_from: number
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        machine_audit_state: number
        credit_type: number
        cover: string
        share_link: string
    }[]
    error?: string
    code?: number
    msg?: string
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'music/extend'                             // Job verb
    jobType: 'music'                           // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        song_id: string
        lyrics: string
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    msg?: string                               // Additional error message
    rawData?: string                           // Raw error data (if available)
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/extend \
     -d '{"song_id": …, "lyrics": "…"}'
```

**JavaScript**
``` javascript
const song_id = 123456789;      
const lyrics = "place your lyrics here";   
const apiUrl = `https://api.useapi.net/v1/mureka/music/extend`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  song_id, lyrics
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
song_id = 123456789
lyrics = "place your lyrics here"   
apiUrl = f"https://api.useapi.net/v1/mureka/music/extend" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "song_id": song_id,
    "lyrics": f"{lyrics}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-lyrics-generate ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-lyrics-generate
## Create an AI-generated lyrics based on your prompt
<small>December 2, 2024 (October 3, 2025)</small>

---
> **https://api.useapi.net/v1/mureka/music/lyrics-generate**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional Mureka API account",
    "prompt": "Optional text prompt"
}
```

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple music configured, this parameter becomes **required**.  

- `prompt` is optional. Use it to guide AI to generate desired lyrics. If omitted AI will generate some random lyrics.

##### Responses 

**200**
**200 OK** 

```json
{
    "lyrics": "<lyrics generated by AI based on your optional prompt>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

Rate limit exceeded. Endpoint called too frequently. Wait at least 1 second before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model
```typescript
{ // TypeScript, all fields are optional
    lyrics: string
    error?: string
    code?: number
    msg?: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/lyrics-generate \
     -d '{"account": "…", "prompt": "…"}'
```

**JavaScript**
``` javascript
const account = "Mureka account";      
const prompt = "Silly song about Santa";      
const apiUrl = `https://api.useapi.net/v1/mureka/music/lyrics-generate`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Mureka account"
prompt = "Silly song about Santa"
apiUrl = f"https://api.useapi.net/v1/mureka/music/lyrics-generate" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": f"{account}",
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-regenerate ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-regenerate
## Regenerate song
<small>December 13, 2024 (January 21, 2026)</small>

---
> **https://api.useapi.net/v1/mureka/music/regenerate**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "song_id": 123456789,
    "start_milliseconds": 123456
}
```

- `song_id` is **required**.  
  The `song_id` value returned by one of the following endpoints: 
  * [GET /music](/docs/api-mureka-v1/get-mureka-music)
  * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
  * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental)   
  * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend)
  * [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate)

- `start_milliseconds` is **required**. Define a starting point for the extension.

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK** 

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "feed_id": 11223344,
    "state": 3,
    "songs": [
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1.1.1",
            "is_regenerate": true,
            "regenerate_from": 123456,            
            "duration_milliseconds": 234567,
            "generate_at": 12345677,
            "genres": [
                "electronic",
                "indie"
            ],
            "moods": [
                "quirky",
                "angry",
                "restless"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "recall": true,
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        },
        {
            "song_id": "user:777-mureka:123456789-song:33445566",
            "title": "<title>",
            "version": "1.1.2",
            "is_regenerate": true,
            "regenerate_from": 123456,            
            "duration_milliseconds": 1234567,
            "generate_at": 12345667,
            "genres": [
                "electronic",
                "world-music"
            ],
            "moods": [
                "dark",
                "quirky",
                "energetic"
            ],
            "mp3_url": "https://<download link>.mp3",
            "share_key": "<share key>",
            "machine_audit_state": 1,
            "credit_type": 1,
            "cover": "https://<cover image>.png",
            "share_link": "https://<share link>"
        }
    ]
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Music regeneration is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka",
    "verb": "music/regenerate",
    "jobType": "music",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "song_id": "user:777-mureka:123456789-song:33445566",
        "start_milliseconds": 123456,
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.  
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Music regeneration completed. Returns full song data with MP3 URLs.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    feed_id: number
    state: number
    songs?: {
        song_id: string
        title: string
        version: string
        is_regenerate: boolean
        regenerate_from: number
        duration_milliseconds: number
        generate_at: number
        genres: string[]
        moods: string[]
        mp3_url: string
        share_key: string
        machine_audit_state: number
        credit_type: number
        cover: string
        share_link: string
    }[]
    error?: string
    code?: number
    msg?: string
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'music/regenerate'                         // Job verb
    jobType: 'music'                           // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        song_id: string
        start_milliseconds: number
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    msg?: string                               // Additional error message
    rawData?: string                           // Raw error data (if available)
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/regenerate \
     -d '{"song_id": …, "start_milliseconds": …}'
```

**JavaScript**
``` javascript
const song_id = 123456789;      
const start_milliseconds = 123456; 
const apiUrl = `https://api.useapi.net/v1/mureka/music/regenerate`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  song_id, start_milliseconds
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
song_id = 123456789
start_milliseconds = 123456
apiUrl = f"https://api.useapi.net/v1/mureka/music/regenerate" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "song_id": song_id,
    "lyrics": start_milliseconds
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-vidoe-generate ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-vidoe-generate
## Create an AI-generated video for your song
<small>December 2, 2024 (October 3, 2025)</small>

---
> **https://api.useapi.net/v1/mureka/music/video-generate**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "song_id": 123456789
}
```

- `song_id` is **required**.  
  The `song_id` value returned by one of the following endpoints: 
  * [GET /music](/docs/api-mureka-v1/get-mureka-music)
  * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create)
  * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)

##### Responses 

**200**
**200 OK** 

```json
{
    "video_url": "https://<download link>.mp4",
    "video_cover_url": "https://<cover image>.png",
    "video_id": 112233445566
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```

**429**
**429 Too Many Requests**

* Rate limit exceeded.  
Endpoint called too frequently. Wait at least 3 seconds before making another call.
```json
{
  "code": 9008,
  "msg": "Too frequently, please try again later."
}
```

* Concurrent job limit exceeded.
All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying.
```json
{
  "error": "Generate multiple task exceed limit. (6323)"
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model
```typescript
{ // TypeScript, all fields are optional
    video_url: string
    video_cover_url: string
    video_id: number
    error?: string
    code?: number
    msg?: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/video-generate \
     -d '{"song_id": …}'
```

**JavaScript**
``` javascript
const song_id = 123456789;      
const apiUrl = `https://api.useapi.net/v1/mureka/music/video-generate`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  song_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
song_id = 123456789
apiUrl = f"https://api.useapi.net/v1/mureka/music/video-generate" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "song_id": song_id
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech-voice ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech-voice
## Clone voice for speech
<small>August 18, 2025</small>

---

This endpoint creates a custom voice clone by uploading an audio sample. The cloned voice can then be used for speech generation via [POST /speech](/docs/api-mureka-v1/post-mureka-speech). Upload clear, high-quality audio MP3 samples (10-60 seconds) for best results. Voice cloning typically takes 60-90 seconds to process.
> **https://api.useapi.net/v1/mureka/speech/voice?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/mpeg
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `title` is **required**. Voice title.  
  Length: 1-50 characters.

- `desc` is **required**. Voice description.  
  Length: 1-500 characters.

- `lang` is **required**. Language code for the voice.  
  Supported values: `en` (English), `zh-Hans` (Simplified Chinese), `zh-Hant` (Traditional Chinese), `ja` (Japanese), `ko` (Korean), `es` (Spanish), `pt` (Portuguese), `de` (German), `fr` (French), `it` (Italian), `ru` (Russian).

##### Request Body

Binary audio file content.  
Supported format: MP3 only (`audio/mpeg` content type).  
Recommended: 10-60 seconds of clear speech for optimal cloning quality.

##### Responses 

**200**
**200 OK**  

```json
{
    "id": 12345678901234,
    "user_id": 23456789012345,
    "title": "Custom Voice",
    "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
    "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
    "language": "en",
    "created_at": 1755483687,
    "description": "Custom cloned voice description",
    "duration_milliseconds": 12520,
    "machine_audit_state": 1
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    id: number
    user_id: number
    title: string
    cover: string
    mp3_url: string
    language: string
    created_at: number
    description: string
    duration_milliseconds: number
    machine_audit_state: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/speech/voice?title=CustomVoice&desc=MyVoiceDescription&lang=en" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" \
   -H "Content-Type: audio/mpeg" \
   --data-binary @voice_sample.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const title = "Custom Voice";
const desc = "My voice description";
const lang = "en";
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const apiUrl = `https://api.useapi.net/v1/mureka/speech/voice?title=${title}&desc=${desc}&lang=${lang}`;
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": file.type,
  },
  body: file,
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
title = "Custom Voice"
desc = "My voice description"
lang = "en"

apiUrl = f"https://api.useapi.net/v1/mureka/speech/voice?title={title}&desc={desc}&lang={lang}"
headers = {
    "Authorization" : f"Bearer {token}",
    "Content-Type": "audio/mpeg"
}

with open('voice_sample.mp3', 'rb') as audio_file:
    response = requests.post(apiUrl, headers=headers, data=audio_file.read())
    print(response, response.json())
```

=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech
## Generate speech
<small>August 18, 2025 (January 21, 2026)</small>

---

This endpoint generates high-quality speech from text using Mureka's advanced text-to-speech technology. You can use either predefined voices or custom cloned voices created via [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice). For multi-speaker conversations, use the `conversation` parameter with different voice IDs. Speech generation typically takes 20-90 seconds depending on text length.

Unlike music generation endpoints, this endpoint has no rate limits or concurrent generation restrictions, allowing unlimited parallel speech generations per account.
> **https://api.useapi.net/v1/mureka/speech**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body

- `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `title` is optional string.  
  Maximum length is 500 characters.

- `text` is required string when not using `conversation`. Must be used together with `voice_id`.  
  Maximum text length is 5000 characters.

- `voice_id` is required number when not using `conversation`. Must be used together with `text`. Get available voice IDs from [GET /speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices).  
  To create a cloned voice, first use [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice) to upload an audio sample and clone the voice.

- `conversation` is optional JSON string. Alternative to `text` and `voice_id`. Must be a JSON string array of objects with `voice_id` (number) and `text` (string) fields. Cannot be used together with `text` and `voice_id`.
  Total text length across all conversation items cannot exceed 5000 characters.

    Example `conversation` JSON:
    ```json
    [
        {"voice_id": 12345, "text": "Hello, welcome to our service!"},
        {"voice_id": 67890, "text": "Thank you for choosing us today."},
        {"voice_id": 12345, "text": "Is there anything I can help you with?"}
    ]
    ```

- `async` is optional, enables fire-and-forget mode (default: `false`).
  When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since speech generation takes 20-90 seconds.

- `replyUrl` is optional, webhook URL for job status callbacks.
  Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

- `replyRef` is optional, custom reference string passed back in webhook callbacks.
  Useful for tracking jobs on your end.

##### Responses 

**200**
**200 OK**  

```json
{
    "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka",
    "title": "Sample Speech Title",
    "preview": "This is a preview of the generated speech content that demonstrates the text-to-speech capabilities.",
    "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png",
    "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3",
    "id": 12345678901234,
    "duration_milliseconds": 15000,
    "audio_quality": 2,
    "state": 3
}
```

**201**
**201 Created**

Job created in async mode (`async: true`). Speech generation is processing in the background.

Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status.

```json
{
    "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka",
    "verb": "speech",
    "jobType": "tts",
    "status": "created",
    "created": "2026-01-20T12:34:56.789Z",
    "request": {
        "account": "12345678901234",
        "text": "Hello, this is a sample text for speech generation.",
        "voice_id": 67890,
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-custom-ref-123"
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**

Returned when the account has an error state preventing API calls.

```json
{
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}
```
Possible error codes:
- `ACCOUNT_ERROR` - Account has a blocking error
- `REFRESH_FAILED` - Automatic token refresh failed
- `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly
- `SESSION_EXPIRED` - Session expired and no auto-refresh available
- `COOKIE_EXPIRED` - Google cookie has expired

To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts).

##### Model

**200 OK (Sync)**

Speech generation completed. Returns full audio data with MP3 URL.

```typescript
{
    jobid: string                              // Job identifier (for later lookup)
    title: string
    preview: string
    cover: string
    mp3_url: string
    id: number
    duration_milliseconds: number
    audio_quality: number
    state: number
}
```

**201 Created (Async)**

Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response.

```typescript
{
    jobid: string                              // Job identifier
    verb: 'speech'                             // Job verb
    jobType: 'tts'                             // Job type
    status: 'created'                          // Job status
    created: string                            // ISO 8601 timestamp
    request: {
        account?: string
        title?: string
        text?: string
        voice_id?: number
        conversation?: string
        async: true
        replyUrl?: string
        replyRef?: string
    }
}
```

**Error**

Error response structure (applies to both sync and async modes).

```typescript
{
    jobid?: string                             // Present for job-related errors
    error: string                              // Error summary message
    code?: number                              // HTTP status code or error code
    rawData?: string                           // Raw error data (if available)
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/mureka/speech" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" \
   -H "Content-Type: application/json" \
   -d '{
     "text": "Hello, this is a sample text for speech generation.",
     "voice_id": 67890
   }'
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/mureka/speech"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Hello, this is a sample text for speech generation.",
    voice_id: 67890
  }),
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/mureka/speech"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "text": "Hello, this is a sample text for speech generation.",
    "voice_id": 67890
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
```

=== URL: https://useapi.net/docs/start-here/setup-pixverse ===
Document URL: https://useapi.net/docs/start-here/setup-pixverse
# <img style="height:1.3em;vertical-align: bottom;" src="/assets/images/pixverse.png"> Setup PixVerse
<small>December 6, 2024</small>

## Table of contents
<small>Approximately 2 minutes to complete setup steps.</small>  

---
> This is the setup guide for [PixVerse API](/docs/api-pixverse-v2). An active [PixVerse.ai](https://pixverse.ai) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

## Create PixVerse.ai account

Navigate to [PixVerse.ai](https://PixVerse.ai) and sign up with an email account. Our API does not support Gmail, Apple, or Discord accounts. We strongly recommend creating a separate PixVerse.ai account designated for API work.

![](/assets/images/pixverse_setup-v2-web.png)

## Configure PixVerse.ai API account

Now that you have a working PixVerse.ai account, configure it for API access using [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful.

## `OPTIONAL` Configure PixVerse API to use the current PixVerse.ai session

The PixVerse.ai website enforces a single active session for a given account. When the API is running, it will terminate your web session. If you want to use the website and run the API simultaneously, you will need to perform the following steps in the **exact** order:

* [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) using your `email` and `password`.
* Navigate to [PixVerse.ai](https://PixVerse.ai), **logout** from your account, and **login** again.
* Using the screenshot below, locate the session `token`.

<details markdown="block">
<summary><small><b>Screenshot</b></small></summary>
<img src="/assets/images/pixverse_setup_v2-token.png">
</details>

* [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) using your `email`, `password` and the obtained `token`.
* Keep the website open. Now, your API and your browser will share the session token, allowing you to use both.

Keep in mind that the API will eventually try to refresh the token, so the approach described above is only effective for a limited time. We strongly recommend not using the API account for any manual generation to avoid any interference with the API.

=== URL: https://useapi.net/docs/api-pixverse-v2 ===
Document URL: https://useapi.net/docs/api-pixverse-v2

# <img style="height:1.3em;vertical-align: bottom;" src="/assets/images/pixverse.png"> PixVerse API v2 

<small>December 6, 2024 (May 13, 2026)</small>

This is an [experimental](/docs/legal) API for [PixVerse.ai](https://pixverse.ai). PixVerse.ai generates videos and images from text and image prompts, supports a large number of video effects, and can extend, upscale, and lipsync videos.

We provide full API support for following PixVerse models:
* PixVerse [videos](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) supports native PixVerse models PixVerse V6 (default), V5.6, V5.5, V5, V5-fast, and [PixVerse C1](https://pixverse.ai) with Off-Peak mode (50% off credits), plus third-party models: [Seedance 2.0 and Seedance 2.0 Fast](https://seed.bytedance.com/seedance) (ByteDance), [Kling O3 and Kling V3](https://www.klingai.com) (Kuaishou), [Grok Imagine](https://x.ai/grok) (xAI), [Veo 3.1 Lite / Standard / Fast](https://deepmind.google/technologies/veo) (Google), [Sora 2 / Sora 2 Pro](https://openai.com/sora) (OpenAI), and [HappyHorse 1.0](https://fal.ai/happyhorse-1.0) (Alibaba). See [model capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model constraints and mode compatibility.
* PixVerse [Motion Control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control) — drive a character image with motion extracted from a reference video. See the [blog example](/blog/260513).
* PixVerse [images](/docs/api-pixverse-v2/post-pixverse-images-create) supports 10 models: [Qwen Image](https://github.com/QwenLM/Qwen2.5-VL), [Nano Banana 2](https://deepmind.google/technologies/gemini/flash/) (Gemini 3.1 Flash), [Nano Banana Pro](https://deepmind.google/technologies/gemini/) (Gemini 3.0), [Nano Banana](https://deepmind.google/technologies/gemini/flash/) (Gemini 2.5 Flash), [Seedream 5.0 Lite](https://seed.bytedance.com/en/seedream), [Seedream 4.5](https://seed.bytedance.com/en/seedream), [Seedream 4.0](https://seed.bytedance.com/en/seedream), [Kling O3](https://www.klingai.com), [Kling 3.0](https://www.klingai.com), and [GPT Image 2.0](https://openai.com/). Pro+ subscription plans include **unlimited image generation** in Relax Mode for select models with generation times ~3s to ~60s based on the model.

Please see the tables below for cost comparison of the web subscription used by this API versus official API subscription.

<details markdown="block">

<summary><small><b>💲 Cost calculator</b></small></summary>

[Subscription plans](https://app.pixverse.ai/subscribe):

#### Pricing

| Plan | Monthly | Credits/mo | $/credit |
|:-----|:-----:|:-----:|:-----:|
| Pro | $30 | 6,000 | $0.00500 |
| Premium | $60 | 15,000 | $0.00400 |
| Ultra | $199 | 25,000 | $0.00796 |

#### Video perks

| Plan | PixVerse Native Off-Peak | Third-party discount |
|:-----|:-----|:-----:|
| Pro | 30% off | — |
| Premium | 50% off | — |
| Ultra | **unlimited free** | **40% off** |

Third-party discount applies to `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`, `grok-imagine`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `sora-2`, `sora-2-pro`, `happyhorse-1.0`. Off-Peak discount applies **only to native PixVerse** (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models don't support off-peak. Native PixVerse peak pricing is the same credits on all plans.

#### Free images (Relax Mode)

| Plan | Free image models |
|:-----|:-----|
| Pro | `qwen-image` |
| Premium | `qwen-image`, `nano-banana`, `nano-banana-2`, `seedream-4.0` |
| Ultra | all 10 models |

Ultra's higher $/credit rate means individual native-PixVerse generations cost more on Ultra than on Premium unless you're saturating Premium's monthly allowance. The calculator above factors all plan rules automatically. The official [API subscription](https://platform.pixverse.ai/billing) doesn't support Off-Peak and is limited to 1/3/5 effect options; the [web subscription](https://app.pixverse.ai/subscribe) used by this API exposes the full 900+ effect catalog.

### Interactive calculator

<!--
=============================================================================
COST CALCULATOR — MAINTENANCE GUIDE
=============================================================================

The JS block below is the source of truth for pricing shown to users. It is
kept in sync with PixVerse's live pricing model via a one-command extraction:

  1. Capture a PixVerse web session (e.g. contextapi + mitmproxy). The
     session needs to contain responses for:
       - POST /creative_platform/pricing/formulas    (video formulas)
       - POST /creative_platform/toc/products/list    (plan details)
     Plus a few generation submit bodies to cross-validate promos.

  2. Run the extractor (in the API repo, not this docs repo):
       node v2-pixverse/tools/extract-pricing.mjs <session-dir> pricing.json
     See extract-pricing.mjs header for full docs + output schema.

  3. Sync the JS constants in the SCRIPT block below from pricing.json:
     - VIDEO{...}          ← ops.t2v.<model> (base, quality, audio, extras)
     - IMAGE{...}          ← mirrors ref_image_pricing (api repo, static)
     - FREE_IMAGES{...}    ← plans[].unlimited_image_models per plan
     - Plan dropdown options ← plans[].{price, credit_monthly_gift, off_peak_discount}
     - durByQuality constraints ← NOT in the extractor; observed from UI.
       Currently only veo-3.1-{lite,standard,fast} @ 1080p → [8] only.

=============================================================================
PLAN-SPECIFIC RULES NOT IN THE API (hand-coded below — verify each sync)
=============================================================================

Everything below is either (a) not exposed in the API response or (b) an
empirical observation. The calculator hard-codes them in compute():

  - Ultra native-PixVerse off-peak = 0 credits (free).
    API shows off_peak_discount=1 for Ultra, so the "free" rule must come
    from a server-side ${ultra_model_discount} variable. Not verified with
    an Ultra-account capture yet.

  - Ultra third-party video discount = external_models_discount (0.6 = 40% off).
    This one IS in the API (plans[].external_models_discount). The
    calculator maps it to `if(!isNative) credits *= 0.6` for Ultra.

  - Off-Peak is NATIVE-PIXVERSE ONLY. Third-party models silently ignore
    off_peak_mode. Calculator hides the checkbox for third-party.

  - preview_mode is NATIVE-PIXVERSE ONLY. Flat 20% discount
    (preview_mode_discount=0.8 for all paid plans). Not quality-gated in
    the formula; the effective output is 360p-ish regardless of requested
    quality. Calculator hides the checkbox for third-party.

  - Per-plan free images come from plans[].unlimited_image_models:
      Pro     → ['qwen-image']
      Premium → ['qwen-image','nano-banana','nano-banana-2','seedream-4.0']
      Ultra   → all 10 models
    (The API uses upstream names like 'gemini-2.5-flash' for 'nano-banana';
     FREE_IMAGES{} uses our public names. Map via ref_image_model in the
     v2-pixverse/pixverse-const.ts api repo file.)

=============================================================================
KNOWN DURATION QUIRKS (UI-level, not formula-level)
=============================================================================

The pricing formula treats duration as a free scalar (multiplied in
directly). These constraints exist only in the PixVerse UI / backend
validator, not the formula:

  - veo-3.1-{lite,standard,fast} @ 1080p  → only duration=8 accepted.
    Encoded as durByQuality: {'1080p':[8]} on those three models.

  - Rumored: veo-3.1-standard may not accept duration=6 at any quality.
    NOT confirmed — leave 6 in durEnum until observed rejection.

If you find new constraints via testing, add them to durByQuality or remove
values from durEnum — no other place to patch.

=============================================================================
-->
<div class="cost-calc" markdown="0">
<style>
.cost-calc { border: 1px solid #ccc; padding: 1em; border-radius: 6px; background: #fafbfc; }
.cost-calc .row { display: flex; gap: 0.75em; align-items: center; margin-bottom: 0.5em; flex-wrap: wrap; }
.cost-calc label.lbl { min-width: 110px; font-weight: 600; }
.cost-calc input[type=number], .cost-calc select { padding: 3px 6px; font-size: 0.95em; }
.cost-calc .result { margin-top: 0.75em; padding: 0.75em; background: #fff; border: 1px solid #dfe2e5; border-radius: 4px; font-size: 1.15em; }
.cost-calc .result b { color: #0366d6; font-size: 1.2em; }
</style>
<div class="row">
  <label for="cc-plan" class="lbl">Plan</label>
  <select id="cc-plan">
    <option value="0.004" data-plan="premium">Premium $60/m (15,000 cr)</option>
    <option value="0.005" data-plan="pro">Pro $30/m (6,000 cr)</option>
    <option value="0.00796" data-plan="ultra">Ultra $199/m (25,000 cr, off_peak is free)</option>
  </select>
</div>
<div class="row">
  <label for="cc-kind" class="lbl">Kind</label>
  <select id="cc-kind">
    <option value="video">Video</option>
    <option value="image">Image</option>
  </select>
</div>
<div class="row">
  <label for="cc-model" class="lbl">Model</label>
  <select id="cc-model"></select>
</div>
<div class="row">
  <label for="cc-quality" class="lbl">Quality</label>
  <select id="cc-quality"></select>
</div>
<div class="row" id="cc-duration-row">
  <label for="cc-duration" class="lbl">Duration (s)</label>
  <select id="cc-duration"></select>
</div>
<div class="row" id="cc-flags"></div>
<div class="result" id="cc-result">—</div>
</div>

<script>
(function(){
var PV={'360p':1,'540p':1.5,'720p':2,'1080p':4};
var VIDEO={
'v6':{base:4,qm:PV,audio:1.25,multishot:1,dur:[1,15]},
'v5.6':{base:4,qm:PV,audio:1.25,dur:[1,10]},
'v5.5':{base:4,qm:PV,audio:1.25,dur:[1,10]},
'v5':{base:4,qm:PV,autoSound:1,autoSpeech:4,dur:[1,10],v5Legacy:true},
'v5-fast':{base:3,qm:PV,autoSound:1,autoSpeech:4,dur:[1,10],v5Legacy:true},
'pixverse-c1':{base:4,qm:PV,audio:1.25,dur:[1,15]},
'seedance-2.0':{base:15,qm:{'480p':1,'720p':2,'1080p':4},dur:[4,15]},
'seedance-2.0-fast':{base:10,qm:{'480p':1,'720p':2},dur:[4,15]},
'kling-v3':{flatByQuality:{'720p':{base:20,label:'Std'},'1080p':{base:25,label:'Pro'}},audio:1.4,dur:[3,15]},
'kling-o3':{flatByQuality:{'720p':{base:25,label:'Std'},'1080p':{base:35,label:'Pro'}},audio:1.4,dur:[3,15]},
'grok-imagine':{base:10,qm:{'480p':1,'720p':1.5},dur:[1,15]},
'veo-3.1-lite':{base:15,qm:{'720p':1,'1080p':2},durEnum:[4,6,8],durByQuality:{'1080p':[8]}},
'veo-3.1-fast':{base:30,qm:{'720p':1,'1080p':1,'4K':3},audio:2,audioForced:true,durEnum:[4,6,8],durByQuality:{'1080p':[8]}},
'veo-3.1-standard':{base:80,qm:{'720p':1,'1080p':1,'4K':3},audio:2,audioForced:true,durEnum:[4,6,8],durByQuality:{'1080p':[8]}},
'sora-2':{base:20,qm:{'720p':1},durEnum:[4,8,12]},
'sora-2-pro':{base:60,qm:{'720p':1,'1080p':1.65},durEnum:[4,8,12]},
'happyhorse-1.0':{base:30,qm:{'720p':1,'1080p':2},dur:[3,15]}
};
var IMAGE={
'qwen-image':{'720p':5,'1080p':10},
'nano-banana':{'1080p':15},
'nano-banana-2':{'512p':16,'1080p':25,'1440p':40,'2160p':60},
'nano-banana-pro':{'1080p':50,'1440p':50,'2160p':90},
'seedream-4.0':{'1080p':10,'1440p':10,'2160p':10},
'seedream-4.5':{'1440p':10,'2160p':10},
'seedream-5.0-lite':{'1440p':15,'1800p':15},
'kling-3.0':{'1080p':10,'1440p':10},
'kling-o3':{'1080p':10,'1440p':10,'2160p':20},
'gpt-image-2.0':{'1080p':15,'1440p':30,'2160p':45}
};
var IMAGE_DETAIL_MULT={'gpt-image-2.0':{'low':1,'medium':2,'high':4}};
var FREE_IMAGES={
pro:{'qwen-image':1},
premium:{'qwen-image':1,'nano-banana':1,'nano-banana-2':1,'seedream-4.0':1},
ultra:{'qwen-image':1,'nano-banana':1,'nano-banana-2':1,'nano-banana-pro':1,'seedream-4.0':1,'seedream-4.5':1,'seedream-5.0-lite':1,'kling-3.0':1,'kling-o3':1,'gpt-image-2.0':1}
};
var $=function(id){return document.getElementById(id);};
var kSel=$('cc-kind'),mSel=$('cc-model'),qSel=$('cc-quality'),dInp=$('cc-duration'),dRow=$('cc-duration-row'),flags=$('cc-flags'),plan=$('cc-plan'),out=$('cc-result');
function clear(el){while(el.firstChild)el.removeChild(el.firstChild);}
function chk(id){var e=$(id);return e?e.checked:false;}
function renderModels(){
  var isImg=kSel.value==='image';
  clear(mSel);
  var keys=Object.keys(isImg?IMAGE:VIDEO);
  keys.forEach(function(k){var o=document.createElement('option');o.value=k;o.textContent=k;mSel.appendChild(o);});
  mSel.value=keys[0];
}
function renderQualities(){
  var isImg=kSel.value==='image';
  var src=isImg?IMAGE[mSel.value]:VIDEO[mSel.value];
  clear(qSel);
  var qs=isImg?Object.keys(src):(src.qm?Object.keys(src.qm):Object.keys(src.flatByQuality));
  qs.forEach(function(q){
    var o=document.createElement('option');o.value=q;
    o.textContent=(!isImg&&src.flatByQuality)?(q+' ('+src.flatByQuality[q].label+')'):q;
    qSel.appendChild(o);
  });
}
function renderDurationAndFlags(){
  var isImg=kSel.value==='image';
  dRow.style.display=isImg?'none':'';
  clear(flags);
  if(isImg){
    var dm=IMAGE_DETAIL_MULT[mSel.value];
    if(dm){
      var w=document.createElement('label');w.style.fontWeight='400';w.style.minWidth='auto';
      w.appendChild(document.createTextNode('detail_level: '));
      var sel=document.createElement('select');sel.id='cc-detail';
      Object.keys(dm).forEach(function(d){
        var o=document.createElement('option');o.value=d;o.textContent=d;sel.appendChild(o);
      });
      sel.value='medium';
      sel.addEventListener('change',compute);
      w.appendChild(sel);flags.appendChild(w);
    }
    return;
  }
  var m=VIDEO[mSel.value];
  clear(dInp);
  var values=[];
  if(m.durByQuality&&m.durByQuality[qSel.value]){values=m.durByQuality[qSel.value].slice();}
  else if(m.durEnum){values=m.durEnum.slice();}
  else{for(var i=m.dur[0];i<=m.dur[1];i++)values.push(i);}
  values.forEach(function(v){var o=document.createElement('option');o.value=v;o.textContent=v;dInp.appendChild(o);});
  dInp.value=values[0];
  function add(id,label,checked){
    var w=document.createElement('label');w.style.fontWeight='400';w.style.minWidth='auto';
    var cb=document.createElement('input');cb.type='checkbox';cb.id=id;cb.checked=checked;
    cb.addEventListener('change',compute);
    w.appendChild(cb);w.appendChild(document.createTextNode(' '+label));
    flags.appendChild(w);
  }
  if(m.audio&&!m.audioForced&&!m.v5Legacy)add('cc-audio','audio',true);
  if(m.audioForced){var n=document.createElement('span');n.textContent='audio: always on';n.style.color='#888';flags.appendChild(n);}
  if(m.v5Legacy){add('cc-autosound','auto_sound',false);add('cc-autospeech','auto_speech',false);}
  if(m.qm===PV){
    add('cc-offpeak','off_peak_mode (PixVerse native models)',false);
    add('cc-preview','preview_mode (PixVerse native models, 20% off)',false);
  }
}
function compute(){
  var isImg=kSel.value==='image';
  var credits=0;
  if(isImg){
    var basePrice=(IMAGE[mSel.value]||{})[qSel.value]||0;
    var dm=IMAGE_DETAIL_MULT[mSel.value];
    if(dm){
      var dl=$('cc-detail')?$('cc-detail').value:'medium';
      basePrice*=dm[dl]||1;
    }
    credits=basePrice;
  }else{
    var m=VIDEO[mSel.value],q=qSel.value,dur=+dInp.value||1;
    var base,qMult=1;
    if(m.flatByQuality){base=m.flatByQuality[q].base;}
    else{base=m.base;qMult=m.qm[q]||1;}
    var cost=base*qMult*dur;
    if(m.v5Legacy){
      var add=0;
      if(chk('cc-autosound'))add+=1;
      if(chk('cc-autospeech'))add+=4;
      cost=(base*qMult+add)*dur;
    }else{
      if(m.audio){var audioOn=m.audioForced||chk('cc-audio');if(audioOn)cost*=m.audio;}
    }
    if(chk('cc-preview')&&m.qm===PV)cost*=0.8;
    credits=Math.ceil(cost);
  }
  var planKey=plan.options[plan.selectedIndex].getAttribute('data-plan');
  if(isImg){
    if((FREE_IMAGES[planKey]||{})[mSel.value])credits=0;
  }else{
    var isNative=VIDEO[mSel.value].qm===PV;
    var offPeakOn=isNative&&chk('cc-offpeak');
    if(planKey==='ultra'){
      if(isNative&&offPeakOn)credits=0;
      else if(!isNative)credits=Math.ceil(credits*0.6);
    }else if(offPeakOn){
      var opMult=planKey==='pro'?0.7:0.5;
      credits=Math.ceil(credits*opMult);
    }
  }
  var dollars=credits*(+plan.value);
  clear(out);
  var b1=document.createElement('b');b1.textContent='$'+dollars.toFixed(3);out.appendChild(b1);
  out.appendChild(document.createTextNode('  ·  '));
  var b2=document.createElement('span');b2.textContent=credits+' credits';b2.style.color='#555';out.appendChild(b2);
}
kSel.addEventListener('change',function(){renderModels();renderQualities();renderDurationAndFlags();compute();});
mSel.addEventListener('change',function(){renderQualities();renderDurationAndFlags();compute();});
qSel.addEventListener('change',function(){renderDurationAndFlags();compute();});
dInp.addEventListener('change',compute);
dInp.addEventListener('input',compute);
plan.addEventListener('change',compute);
renderModels();renderQualities();renderDurationAndFlags();compute();
})();
</script>

### Other

| Feature | Web | Official API |
|:--------|:----|:----|
| Upscale ([POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale)) | 6 cr / s ($0.024/s at Premium) | n/a |
| Concurrent generations | 8 | 5 |
| Effects available | full 900+ catalog | 3 |

Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include **unlimited image generation** in Relax Mode for select models — Ultra ($199/m) covers ALL image models.

</details>

[Setup PixVerse](/docs/start-here/setup-pixverse)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(May 13, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-pixverse-v2.txt) <small>Feed this to your LLM to build integrations</small>

Check out generated videos on <a href="https://www.youtube.com/watch?v=YxHh_FdCo9c"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg"> YouTube</a>.  

Blogs:
* [Motion Control](/blog/260513)
* [HappyHorse 1.0](/blog/260504)
* [PixVerse V6 — Multi-Shot, 15s 1080p, Audio](/blog/260405)
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [PixVerse Images — Qwen Image, Nano Banana / 2 / Pro, Seedream 4.0 / 4.5 / 5.0 Lite](/blog/260309)
* [PixVerse v5.6](/blog/260127)
* [PixVerse Modify](/blog/260126)
* [PixVerse v5.5](/blog/251205)
* [PixVerse v5](/blog/250829)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/pixverse_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/pixverse_api</a>

=== URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-accounts-email ===
Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-accounts-email
## Delete PixVerse API account
<small>December 6, 2024</small>

---
> **https://api.useapi.net/v2/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v2/pixverse/accounts/<email> 
```

**JavaScript**
``` javascript
const email = "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
email = "Previously configured account email" 
apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-images-image_id ===
Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-images-image_id
## Delete an image
<small>March 9, 2026</small>

---
> **https://api.useapi.net/v2/pixverse/images/`image_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path parameter
- `image_id` is **required**. Specify the image_id you want to delete.

##### Responses

**200**
**200 OK**

Image was successfully deleted.

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v2/pixverse/images/image_id"
```

**JavaScript**
``` javascript
const token = "API token";
const image_id = "image_id to delete";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/${image_id}`;
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
image_id = "image_id to delete"
apiUrl = f"https://api.useapi.net/v2/pixverse/images/{image_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-scheduler-video_id ===
Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-scheduler-video_id
## Cancel video or image currently being executed by the API
<small>December 6, 2024 (March 9, 2026)</small>

---

Remove `video_id` or `image_id` generation tracking by the API.
> **https://api.useapi.net/v2/pixverse/scheduler/`id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `id` is **required**. Specify `video_id` or `image_id` you want to cancel.

##### Responses 

**204**
**204 No Content**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Unable to locate running video_id <video_id>"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v2/pixverse/scheduler/video_id" 
```

**JavaScript**
``` javascript
const video_id = "video_id to cancel"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/${video_id}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
video_id = "video_id to cancel" 
apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/{video_id}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-videos-video_id ===
Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-videos-video_id
## Delete a video
<small>December 6, 2024</small>

---
> **https://api.useapi.net/v2/pixverse/videos/`video_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `video_id` is **required**. Specify the video_id you want to delete.   

##### Responses 

**200**
**200 OK**  

Video was successfully deleted.

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v2/pixverse/videos/video_id" 
```

**JavaScript**
``` javascript
const token = "API token";
const video_id = "video_id to delete"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/${video_id}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
video_id = "video_id to delete"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/{video_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts-email ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts-email
## Retrieve PixVerse API account configuration for `email` 
<small>December 6, 2024</small>

---
> **https://api.useapi.net/v2/pixverse/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "email": "<account email>",
  "password": "…secured…",  
  "maxJobs": 3,
  "jwt": {
    "AccountId": 66778899,
    "ExpireTime": 123456789,
    "ExpireTimeUTC": "2025-01-01T12:13:14.000Z",
    "Username": "<username>",
    "token": "abc…secured…cde"
  }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string
  password: string
  maxJobs: number
  jwt: {
    AccountId: number
    ExpireTime: number
    ExpireTimeUTC: string
    Username: string
    token: string
  }  
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/pixverse/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts
## Retrieve PixVerse API accounts configuration
<small>December 6, 2024</small>

---

For your convenience, you can specify your PixVerse configuration values under your PixVerse account. If you specify multiple PixVerse accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to PixVerse.

This endpoint retrieves the complete list of configured API accounts for PixVerse.
> **https://api.useapi.net/v2/pixverse/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "<email #1>": {
        "email": "<email #1>",
        "jwt": {
            "AccountId": 1122334455,
            "ExpireTime": 123456789,
            "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
            "Username": "<username>",
            "token": "abc…secured…cde",
        },
        "maxJobs": 8,
        "password": "…secured…"
    },
    "<email #2>": {
        "email": "<email #2>",
        "jwt": {
            "AccountId": 66778899,
            "ExpireTime": 123456789,
            "ExpireTime": 123456789,
            "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
            "Username": "<username>",
            "token": "abc…secured…cde",
        },
        "maxJobs": 3,
        "password": "…secured…"
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [email: string]: {
        email: string
        jwt: {
            AccountId: number
            ExpireTime: number
            ExpireTimeUTC: string
            Username: string
            token: string
        }
        maxJobs: number
        password: string
    }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/pixverse/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v2/pixverse/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v2/pixverse/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features
## Retrieve your PixVerse.ai account information (credits etc)
<small>December 6, 2024</small>

---

Retrieve your [PixVerse.ai](https://PixVerse.ai) account information, see [Setup PixVerse](/docs/start-here/setup-pixverse) for details.
> **https://api.useapi.net/v2/pixverse/features/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "user_id": 11223344,
    "member_id": 5566778899,
    "product_id": 9988776655,
    "plan_name": "Pro Plan",
    "next_plan_name": "Pro Plan",
    "next_plan_type": 2,
    "current_plan_type": 2,
    "type": 0,
    "credit_daily": 30,
    "credit_daily_gift": 30,
    "initial_credit_gift": 0,
    "credit_monthly": 5600,
    "credit_monthly_gift": 6000,
    "credit_package": 20,
    "expired_date": "2025-01-01T21:21:21Z",
    "price": "30",
    "billing_period": 1,
    "next_billing_period": 1,
    "billing_renewal_date": "2025-01-01T21:21:21Z",
    "payment": 1,
    "invoice_url": "https://stripe.pay.pixverse.ai/...",
    "stripe_bill_url": "https://stripe.pay.pixverse.ai/...",
    "gen_simultaneously": 5,
    "allow_fast_mode": 1,
    "allow_relaxed_mode": 1,
    "allow_use_new_feat": 1,
    "allow_private_generate": 1,
    "remove_watermark": 1,
    "allow_purchase_credit": 1,
    "sub_order_in_progress": 0,
    "allow_effect": 1
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    user_id: number
    member_id: number
    product_id: number
    plan_name: string
    next_plan_name: string
    next_plan_type: number
    current_plan_type: number
    type: number
    credit_daily: number
    credit_daily_gift: number
    initial_credit_gift: number
    credit_monthly: number
    credit_monthly_gift: number
    credit_package: number
    expired_date: string
    price: string
    billing_period: number
    next_billing_period: number
    billing_renewal_date: string
    payment: number
    invoice_url: string
    stripe_bill_url: string
    gen_simultaneously: number
    allow_fast_mode: number
    allow_relaxed_mode: number
    allow_use_new_feat: number
    allow_private_generate: number
    remove_watermark: number
    allow_purchase_credit: number
    sub_order_in_progress: number
    allow_effect: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/features/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/features/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/features/?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images-image_id ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images-image_id
## Retrieve a generated image
<small>March 9, 2026</small>

---

Use this endpoint to retrieve a generated image. Attempting to retrieve an image that is still processing will return the current status. Poll until `image_status_final` is `true`.

To create images, use [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create).
> **https://api.useapi.net/v2/pixverse/images/`image_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path parameter
- `image_id` is **required**. Specify the image_id you want to retrieve (from `success_ids` array returned by [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create)).

##### Responses

**200**
**200 OK**

```json
{
    "image_id": "user:<userid>-pixverse:<email>-image:<number>",
    "image_status": 1,
    "account_id": 12345678,
    "model": "seedream-4.0",
    "prompt": "<prompt>",
    "quality": "1080p",
    "aspect_ratio": "auto",
    "seed": 12345,
    "image_url": "https://media.pixverse.ai/...webp",
    "output_width": 1920,
    "output_height": 1080,
    "customer_img_paths": [],
    "customer_img_urls": null,
    "queue_data": {
        "estimated_gen_time": 60,
        "processing_start_time": "2026-03-08T00:30:00Z",
        "queue_count": 0,
        "queue_time": 1
    },
    "created_at": "2026-03-08T00:30:00Z",
    "updated_at": "2026-03-08T00:31:00Z",
    "image_status_name": "COMPLETED",
    "image_status_final": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

The image was deleted or not found.

```json
{
    "error": "The original image has been deleted"
}
```

##### Image Status Values

| image_status | image_status_name | image_status_final | Description |
|:------------|:------------------|:-------------------|:------------|
| 1 | COMPLETED | true | Image ready, check `image_url` |
| 5 | QUEUED | false | Waiting in queue |
| 7 | MODERATED | true | Content moderation triggered |
| 9 | GENERATING | false | Image is being generated |
| 10 | PROCESSING | false | Post-processing |

##### Model

```typescript
{   // TypeScript, all fields are optional
    image_id: string
    image_status: number
    account_id: number
    asset_id: number
    asset_source: number
    asset_type: number
    create_mode: string
    creation_type: number
    model: string
    prompt: string
    quality: string
    aspect_ratio: string
    seed: number
    image_path: string
    image_url: string
    output_width: number
    output_height: number
    customer_img_paths: string[]
    customer_img_urls: string[] | null
    platform: string
    queue_data?: {
        estimated_gen_time: number
        processing_start_time: string
        queue_count: number
        queue_time: number
    }
    created_at: string
    updated_at: string
    is_collected: boolean
    water_mark: boolean
    media_locked: number
    // added
    image_status_name: string
    image_status_final: boolean
    error: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/images/image_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const image_id = "image_id to retrieve";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/${image_id}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
image_id = "image_id to retrieve"
apiUrl = f"https://api.useapi.net/v2/pixverse/images/{image_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images
## Retrieve the list of images
<small>December 6, 2024 (March 9, 2026)</small>

---

Retrieve the list of images, this will include those currently being generated or queued. Check the `image_status_name` field for the status and the field `image_status_final` to determine if the provided status is the final status.

The API internally uses the field `image_status` to calculate values for `image_status_name` and `image_status_final`. See below for the known statuses map:

| image_status | image_status_name | image_status_final |
|--------|-------------------|--------------------|
| 1      | COMPLETED         | true               |
| 5      | QUEUED            | false              |
| 7      | MODERATED         | true               |
| 9      | GENERATING        | false              |
| 10     | PROCESSING        | false              |
> **https://api.useapi.net/v2/pixverse/images/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `limit` is optional, specify the number of images to return. Default 50.

- `offset` is optional, specify the offset from where to start.

##### Responses

**200**
**200 OK**

```json
{
    "data": [
        {
            "image_id": "user:<userid>-pixverse:<email>-image:11223344",
            "image_status": 1,
            "account_id": 33445566,
            "asset_id": 0,
            "asset_source": 1,
            "asset_type": 0,
            "create_mode": "t2i",
            "creation_type": 0,
            "model": "qwen-image",
            "prompt": "<prompt>",
            "quality": "720p",
            "aspect_ratio": "1:1",
            "seed": 123456,
            "image_path": "image/...",
            "image_url": "https://media.pixverse.ai/image/...webp",
            "output_width": 720,
            "output_height": 720,
            "customer_img_paths": [],
            "customer_img_urls": null,
            "platform": "",
            "queue_data": null,
            "created_at": "2026-03-09T12:34:56Z",
            "updated_at": "2026-03-09T12:34:58Z",
            "is_collected": false,
            "water_mark": false,
            "media_locked": 0,
            "image_status_name": "COMPLETED",
            "image_status_final": true
        }
    ],
    "next_offset": 50,
    "total": 12
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model

```typescript
{   // TypeScript, all fields are optional
  data: {
    image_id: string
    image_status: number
    account_id: number
    asset_id: number
    asset_source: number
    asset_type: number
    create_mode: string
    creation_type: number
    model: string
    prompt: string
    quality: string
    aspect_ratio: string
    seed: number
    image_path: string
    image_url: string
    output_width: number
    output_height: number
    customer_img_paths: string[]
    customer_img_urls: string[] | null
    platform: string
    queue_data: {
        estimated_gen_time: number
        processing_start_time: string
        queue_count: number
        queue_time: number
    } | null
    created_at: string
    updated_at: string
    is_collected: boolean
    water_mark: boolean
    media_locked: number
    // added
    image_status_name: string
    image_status_final: boolean
  }[]
  next_offset: number
  total: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/images/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/?email=${email}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/images/?email={email}"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler-available ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler-available
## Retrieve the list of videos and images currently running via the API along with the available account capacity
<small>December 6, 2024 (March 9, 2026)</small>

---

This endpoint retrieves the list of videos and images currently running via the API along with the available account capacity. Each executing item includes `id` and `type` (`video` or `image`).

If you want to get all videos or images currently being executed including those manually initiated from PixVerse.ai website use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos) or [GET /images](/docs/api-pixverse-v2/get-pixverse-images).
> **https://api.useapi.net/v2/pixverse/scheduler/available**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
{
    "executing": [
        {
            "id": "user:user_id-pixverse:email-video:id1",
            "type": "video",
            "started": "2024-09-25T01:55:16.128Z",
            "elapsed": "03:57",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        },
        {
            "id": "user:user_id-pixverse:email-image:id2",
            "type": "image",
            "started": "2024-09-25T01:58:18.555Z",
            "elapsed": "00:35",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        }
    ],
    "available": [
        {
            "email": "<email_1>",
            "maxJobs": 5,
            "executing": 0,
            "available": 5
        },
        {
            "email": "<email_2>",
            "maxJobs": 8,
            "executing": 3,
            "available": 2
        },
        {
            "email": "<email_N>",
            "maxJobs": 3,
            "executing": 2,
            "available": 1
        }
    ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    executing: {
        id: string
        type: 'video' | 'image'
        started: string
        elapsed: string
        replyUrl: string
        replyRef: string
    }[]
    available: {
        email: string
        maxJobs: number
        executing: number
        available: number
    }[]
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/available`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/available"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler
## Retrieve the list of videos and images currently being executed by the API
<small>December 6, 2024 (March 9, 2026)</small>

---

This endpoint retrieves the list of videos and images currently being executed by the API. Each item includes `id` and `type` (`video` or `image`). If you want to get all videos or images currently being executed including those manually initiated from PixVerse.ai website use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos) or [GET /images](/docs/api-pixverse-v2/get-pixverse-images).
> **https://api.useapi.net/v2/pixverse/scheduler/**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
[
    {
        "id": "user:user_id-pixverse:email-video:id1",
        "type": "video",
        "started": "2024-09-25T01:55:16.128Z",
        "elapsed": "03:57",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "id": "user:user_id-pixverse:email-image:id2",
        "type": "image",
        "started": "2024-09-25T01:58:18.555Z",
        "elapsed": "00:35",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    id: string
    type: 'video' | 'image'
    started: string
    elapsed: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-effects ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-effects
## Retrieve the list of effects 
<small>December 6, 2024 (May 12, 2026)</small>

---

The returned `effect_type` field encodes the number of input images the template accepts (as a string):
- `"1"` = exactly one image (e.g., face swap, dance effects)
- `"2"` = exactly two images (e.g., hug, kiss effects)
- `"3"`, `"4"`, `"5"` = multi-input effects (e.g., Family Reunion accepts up to 5 portraits) — pass via `frame_1_path..frame_5_path` on [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). For these templates, the minimum is 2 input images and the maximum is `effect_type`.

The `template_type` field distinguishes output kind:
- `1` = video output
- `2` = image output (1-second still — the response carries `image_id` instead of `video_id`)

The `template_model` field identifies the underlying engine (`v5`, `v5.5`, `v5.6`, `v6`, `image_v5`, `image_v6`, `image_v7`, `gemini-2.5-flash`, `gemini-3.0`, `qwen-image`, `""`). When you invoke a template, you do **not** need to (and should not) pass a `model` parameter — the template's engine is authoritative.

The `qualities` field is the closed list of quality options the template accepts. Some templates only allow `["1080p"]` or `["360p", "540p", "720p"]` — calling with any other value is rejected.

The total credit cost for a template is `video_base_cost + fixed_cost`.
> **https://api.useapi.net/v2/pixverse/videos/effects?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "items": [
        {
            "template_id": 384628677917440,
            "display_name": "Family Reunion",
            "workflow_tag": "meta_nanopro_muti_it2v_260115",
            "display_prompt": "This moment is what home means.",
            "effect_type": "5",
            "template_type": 1,
            "template_model": "v5",
            "template_paid": 1,
            "supported_features": [2],
            "duration": 5,
            "qualities": ["360p", "540p", "720p", "1080p"],
            "score": 8.42,
            "hot_count": 0,
            "created_at": "2026-04-15T07:12:08Z",
            "updated_at": "2026-05-12T00:01:54Z",
            "author_info": {
                "account_id": 1001075,
                "username": "",
                "nickname": "maxcasu",
                "avatar": "https://media.pixverse.ai/upload%2F…jpg"
            },
            "category_ids": [157, 191],
            "video_base_cost": 20,
            "fixed_cost": 20,
            "example_text": "Upload 5 portrait photos",
            "thumbnail_path": "https://media.pixverse.ai/…jpg",
            "thumbnail_video_path": "https://media.pixverse.ai/…mp4",
            "thumbnail_gif_path": "https://media.pixverse.ai/…webp",
            "app_thumbnail_url": "https://media.pixverse.ai/…jpg",
            "app_thumbnail_video_url": "https://media.pixverse.ai/…mp4",
            "app_thumbnail_gif_url": "https://media.pixverse.ai/…webp",
            "audio_path": "https://media.pixverse.ai/…mp3",
            "marker": ""
        },
        {
            "template_id": 377433499832192,
            "display_name": "Tattoo Removal",
            "workflow_tag": "i2i_image_v5_…",
            "display_prompt": "Remove tattoos cleanly from any photo.",
            "effect_type": "1",
            "template_type": 2,
            "template_model": "image_v5",
            "template_paid": 0,
            "supported_features": [2],
            "duration": 1,
            "qualities": ["1080p"],
            "score": 6.5,
            "hot_count": 0,
            "created_at": "2026-02-20T10:00:00Z",
            "updated_at": "2026-05-12T00:01:54Z",
            "author_info": {
                "account_id": 1001075,
                "username": "",
                "nickname": "pixverse",
                "avatar": ""
            },
            "category_ids": [169],
            "video_base_cost": 20,
            "fixed_cost": 10,
            "example_text": "Upload a portrait with a visible tattoo",
            "thumbnail_path": "https://media.pixverse.ai/…jpg",
            "thumbnail_video_path": "",
            "thumbnail_gif_path": "",
            "app_thumbnail_url": "https://media.pixverse.ai/…jpg",
            "app_thumbnail_video_url": "",
            "app_thumbnail_gif_url": "",
            "audio_path": "",
            "marker": ""
        }
    ],
    "total": 917,
    "next_offset": 0
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model

```typescript
{   // TypeScript
  items: {
    template_id: number
    display_name: string
    workflow_tag: string
    display_prompt: string
    effect_type: string        // "1" or "2" = exact count required; "3"/"4"/"5" = multi-input (min 2, max effect_type)
    template_type: number      // 1 = video output, 2 = image output (1-second still, returns image_id)
    template_model: string     // engine: v5, v5.5, v5.6, v6, image_v5, image_v6, image_v7, gemini-2.5-flash, gemini-3.0, qwen-image, ""
    template_paid: number      // 0 = free, 1 = paid tier required
    supported_features: number[] | null  // feature flags (pass-through)
    duration: number           // output duration in seconds (1 for image templates; 5–21 for video templates)
    qualities: string[]        // allowed quality values — passing any other rejects with 400
    score: number              // popularity score
    hot_count: number          // running engagement counter
    created_at: string         // ISO timestamp the template was published
    updated_at: string         // ISO timestamp of last metadata update
    author_info: {             // template author
      account_id: number
      username: string
      nickname: string
      avatar: string           // full URL or ""
    }
    category_ids: number[]     // sub-category IDs this template belongs to
    video_base_cost: number    // base credit cost
    fixed_cost: number         // template-specific extra cost (template_paid templates typically charge fixed_cost)
    example_text: string       // usage hint, e.g. "Upload 5 portrait photos"
    thumbnail_path: string     // thumbnail URL (alias for app_thumbnail_url)
    thumbnail_video_path: string
    thumbnail_gif_path: string
    app_thumbnail_url: string  // canonical thumbnail URL
    app_thumbnail_video_url: string
    app_thumbnail_gif_url: string
    audio_path: string         // template's built-in audio track (full URL); empty when none
    marker: string             // "new", "hot", "default", or ""
  }[]
  total: number
  next_offset: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/effects?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/effects?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/effects?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-restyles ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-restyles
## Retrieve the list of styles used for restyling
<small>March 31, 2025 (January 27, 2026)</small>

<span class="required-input-field"><b>PixVerse website no longer supports Restyle. This endpoint no loner available.</b></span>

---
> **https://api.useapi.net/v2/pixverse/videos/restyles?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of videos to return. Default 100.

- `offset` is optional, specify the offset from where to start.

##### Responses 

**200**
**200 OK**  

```json
{
    "items": [
        {
            "restyle_id": 322004186061696,
            "display_name": "Van Gogh",
            "restyle_prompt": "Impressionistic Van Gogh style, with thick, expressive brushstrokes and vibrant, swirling color palettes, reminiscent of classic paintings, featuring textured yet simplified characters and environments full of movement and emotional depth.",
            "thumbnail_path": "asset/template/vangogh_1.png",
            "thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fvangogh_1.png",
            "marker": "new",
            "created_at": "2025-02-12T09:02:40Z",
            "updated_at": "2025-02-18T02:24:14Z"
        },
        {
            "restyle_id": 322876019426368,
            "display_name": "Ghibli Animation",
            "restyle_prompt": "Ghibli style, with whimsical, fluid animation and soft, earthy color palettes, reminiscent of Studio Ghibli’s enchanting worlds, featuring simplified yet lush characters and environments made of hand-painted textures and dreamlike, nature-inspired elements.",
            "thumbnail_path": "asset/template/ghibli_1.png",
            "thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fghibli_1.png",
            "marker": "new",
            "created_at": "2025-02-17T07:17:40Z",
            "updated_at": "2025-02-17T10:19:09Z"
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    items: {
        restyle_id: number
        restyle_tag: string
        display_name: string
        restyle_prompt: string
        thumbnail_path: string
        thumbnail_url: string
        thumbnail_video_path: string
        thumbnail_video_url: string
        show_status: string
        app_show_status: string
        marker: string
        display_prompt: string
        i18n_json: object | null
        score: number
        example_list: string
        qualities: any | null
        thumbnail_gif_path: string
        thumbnail_gif_url: string
        app_thumbnail_path: string
        app_thumbnail_url: string
        app_thumbnail_video_path: string
        app_thumbnail_video_url: string
        app_thumbnail_gif_path: string
        app_thumbnail_gif_url: string
        audio_path: string
        audio_url: string
        is_del: number
        is_pinned: string
        created_at: string
        updated_at: string
    }[]
    next_offset: number
    total: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/restyles?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/restyles?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/restyles?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-video_id ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-video_id
## Retrieve a generated video or image information
<small>December 6, 2024 (March 9, 2026)</small>

---

Use this endpoint to retrieve a generated video or image information. Attempting to retrieve a video that is still processing will result in a `404` response. Use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve all available videos.

For dedicated image generation and retrieval, see [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create) and [GET images/image_id](/docs/api-pixverse-v2/get-pixverse-images-image_id).
> **https://api.useapi.net/v2/pixverse/videos/`video_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `video_id` is **required**. Specify the video_id or image_id you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:112233445566",
    "video_status": 1,
    "account_id": 33445566,
    "created_at": "2024-11-11T12:34:56Z",
    "first_frame": "https://media.pixverse.ai/....jpg",
    "output_width": 2560,
    "output_height": 1472,
    "original_video_id": "user:<userid>-pixverse:<email>-video:66778899",
    "upscaled": 1,
    "prompt": "<prompt>",
    "model": "v3",
    "negative_prompt": "<negative prompt>",
    "quality": "360p",
    "motion_mode": "normal",
    "asset_id": 0,
    "auto_character_prompt": 0,
    "seed": 0,
    "likes": 0,
    "model_name": "",
    "queue_data": {
        "queue_time": 1,
        "queue_count": 0
    },
    "video_duration": 5,
    "last_frame": "",
    "extended": 0,
    "lip_sync": null,
    "url": "https://media.pixverse.ai/...mp4",
    "img_id": 115994841,
    "img_url": "https://media.pixverse.ai/...webp",
    "duration": 5,
    "motion_brush": "",
    "asset_name": "",
    "asset_img_url": "",
    "remove_watermark": 1,
    "nick_name": "<name>",
    "avatar": "https://media.pixverse.ai/...jpeg",
    "aspect_ratio": "",
    "camera_movement": "default",
    "relation_type": 0,
    "style": "",
    "template_id": 307489548427968,
    "template_name": "Crazy Cat Woman",
    "template_thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.png",
    "template_thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.mp4",
    "template_i18n_json": "{\"zh-CN\":{\"display_name\":\"疯狂猫女变身\",\"display_prompt\":\"变身妖娆猫女，撩翻全场！\"}}",
    "workflow_tag": "",
    "customer_paths": null,
    "platform": "",
    "off_peak": 0,
    "video_status_name": "COMPLETED",
    "video_status_final": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

The video was deleted, not found, or is still processing.

```json
{
    "error": "The original video has been deleted"
}
```

##### Model 
  
```typescript
{   // TypeScript, all fields are optional
    video_id: string
    video_status: number
    account_id: number
    created_at: string
    first_frame: string
    output_width: number
    output_height: number
    original_video_id: number
    upscaled: number
    prompt: string
    model: string
    negative_prompt: string
    quality: string
    motion_mode: string
    asset_id: number
    auto_character_prompt: number
    seed: number
    likes: number
    model_name: string
    queue_data?: {
        queue_time: number
        queue_count: number
        estimated_gen_time?: number
        processing_start_time?: string
    }
    video_duration: number
    last_frame: string
    extended: number
    lip_sync?: any
    original_sound_switch: number
    sound_effect_switch: number
    lip_sync_switch: number
    is_sound: number
    url: string
    video_path: string
    img_id: number
    img_url: string
    img_path: string
    customer_img_path?: string
    customer_img_url?: string
    duration: number
    motion_brush: string
    asset_name: string
    asset_img_url: string
    remove_watermark: number
    nick_name: string
    avatar: string
    aspect_ratio: string
    camera_movement: string
    relation_type: number
    style: string
    template_id: number
    template_name: string
    template_thumbnail_url: string
    template_thumbnail_video_url: string
    template_thumbnail_gif_url: string
    template_i18n_json: string
    workflow_tag: string
    customer_paths?: {
        customer_img_url?: string
        customer_img_path?: string
        lip_sync_audio_url?: string
        lip_sync_audio_path?: string
        lip_sync_tts_content?: string
        sound_effect_content?: string
        lip_sync_tts_audio_path?: string
        lip_sync_tts_speaker_id?: string
        customer_video_url?: string
        customer_video_path?: string
        customer_video_duration?: number
        customer_first_frame?: string
        customer_last_frame?: string
        customer_first_frame_url?: string
        customer_last_frame_url?: string
        customer_img_urls?: string[]
        customer_img_paths?: string[]
        customer_lip_sync_audio_path?: string
    }
    platform: string
    create_mode: string
    qualities?: string[] | null
    lora_weight: number
    restyle_id: number
    restyle_prompt: string
    off_peak: number
    // added
    video_status_name: string
    video_status_final: boolean
    error: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/video_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const video_id = "video_id to retrieve"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/${video_id}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
video_id = "video_id to retrieve"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/{video_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-voices ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-voices
## Retrieve the list of voices for lipsync
<small>December 6, 2024</small>

---
> **https://api.useapi.net/v2/pixverse/videos/voices/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "tts_list": [
        {
            "speaker_id": "1",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/1.mp3",
            "display_name": "Emily"
        },
        {
            "speaker_id": "2",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/2.mp3",
            "display_name": "James"
        },
        {
            "speaker_id": "3",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/3.mp3\n",
            "display_name": "Isabella"
        },
        {
            "speaker_id": "4",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/4.mp3",
            "display_name": "Liam"
        },
        {
            "speaker_id": "5",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/5.mp3",
            "display_name": "Chloe"
        },
        {
            "speaker_id": "6",
            "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/6.mp3",
            "display_name": "Adrian"
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    tts_list: {
        speaker_id: string
        url: string
        display_name: string
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/voices/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/voices/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/voices/?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos
## Retrieve the list of videos 
<small>December 6, 2024 (July 8, 2025)</small>

---

Retrieve the list of videos, this will include those currently being generated or queued. Check the `video_status_name` field for the status and the field `video_status_final` to determine if the provided status is the final status.

The API internally uses the field `video_status` to calculate values for `video_status_name` and `video_status_final`. See below for the known statuses map:

| video_status | video_status_name | video_status_final |
|--------|-------------------|--------------------|
| 1      | COMPLETED         | true               |
| 5      | QUEUED            | true               |
| 7      | MODERATED         | true               |
| 9      | GENERATING        | false              |
| 10     | GENERATING        | false              |

If field `off_peak` set to `1` that means this video will be generated during off-peak hours.
> **https://api.useapi.net/v2/pixverse/videos/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of videos to return. Default 40.

- `offset` is optional, specify the offset from where to start.

##### Responses 

**200**
**200 OK**  

```json
{
    "data": [
        {
            "video_id": "user:<userid>-pixverse:<email>-video:11223344",
            "video_status": 10,
            "account_id": 33445566,
            "created_at": "2024-11-11T12:34:56Z",
            "first_frame": "",
            "output_width": 0,
            "output_height": 0,
            "original_video_id": 0,
            "upscaled": 0,
            "prompt": "<prompt>",
            "model": "v3",
            "negative_prompt": "",
            "quality": "540p",
            "motion_mode": "normal",
            "asset_id": 0,
            "auto_character_prompt": 0,
            "seed": 123456,
            "likes": 0,
            "model_name": "",
            "queue_data": {
                "queue_time": 1,
                "queue_count": 0
            },
            "video_duration": 5,
            "last_frame": "",
            "extended": 0,
            "lip_sync": {},
            "url": "https://media.pixverse.ai/...mp4",
            "img_id": 55667788,
            "img_url": "https://media.pixverse.ai/...webp",
            "duration": 5,
            "motion_brush": "",
            "asset_name": "",
            "asset_img_url": "",
            "remove_watermark": 0,
            "nick_name": "<name>",
            "avatar": "https://media.pixverse.ai/...jpeg",
            "aspect_ratio": "3:4",
            "camera_movement": "default",
            "relation_type": 0,
            "style": "",
            "template_id": 0,
            "template_name": "",
            "template_thumbnail_url": "",
            "template_thumbnail_video_url": "",
            "template_i18n_json": "",
            "workflow_tag": "",
            "customer_paths": null,
            "platform": "",
            "video_status_name": "GENERATING",
            "off_peak": 0,
            "video_status_final": false
        },
        {
            "video_id": "user:<userid>-pixverse:<email>-video:112233445566",
            "video_status": 1,
            "account_id": 33445566,
            "created_at": "2024-11-11T12:34:56Z",
            "first_frame": "https://media.pixverse.ai/....jpg",
            "output_width": 2560,
            "output_height": 1472,
            "original_video_id": "user:<userid>-pixverse:<email>-video:66778899",
            "upscaled": 1,
            "prompt": "<prompt>",
            "model": "v3",
            "negative_prompt": "<negative prompt>",
            "quality": "360p",
            "motion_mode": "normal",
            "asset_id": 0,
            "auto_character_prompt": 0,
            "seed": 0,
            "likes": 0,
            "model_name": "",
            "queue_data": {
                "queue_time": 1,
                "queue_count": 0
            },
            "video_duration": 5,
            "last_frame": "",
            "extended": 0,
            "lip_sync": null,
            "url": "https://media.pixverse.ai/...mp4",
            "img_id": 115994841,
            "img_url": "https://media.pixverse.ai/...webp",
            "duration": 5,
            "motion_brush": "",
            "asset_name": "",
            "asset_img_url": "",
            "remove_watermark": 1,
            "nick_name": "<name>",
            "avatar": "https://media.pixverse.ai/...jpeg",
            "aspect_ratio": "",
            "camera_movement": "default",
            "relation_type": 0,
            "style": "",
            "template_id": 307489548427968,
            "template_name": "Crazy Cat Woman",
            "template_thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.png",
            "template_thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.mp4",
            "template_i18n_json": "{\"zh-CN\":{\"display_name\":\"疯狂猫女变身\",\"display_prompt\":\"变身妖娆猫女，撩翻全场！\"}}",
            "workflow_tag": "",
            "customer_paths": null,
            "platform": "",
            "off_peak": 1,
            "video_status_name": "COMPLETED",
            "video_status_final": true
        }
    ],
    "next_offset": 40,
    "total": 55
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
  {
    video_id: string
    video_status: number
    account_id: number
    created_at: string
    first_frame: string
    output_width: number
    output_height: number
    original_video_id: number
    upscaled: number
    prompt: string
    model: string
    negative_prompt: string
    quality: string
    motion_mode: string
    asset_id: number
    auto_character_prompt: number
    seed: number
    likes: number
    model_name: string
    queue_data?: {
        queue_time: number
        queue_count: number
        estimated_gen_time?: number
        processing_start_time?: string
    }
    video_duration: number
    last_frame: string
    extended: number
    lip_sync?: any
    original_sound_switch: number
    sound_effect_switch: number
    lip_sync_switch: number
    is_sound: number
    url: string
    video_path: string
    img_id: number
    img_url: string
    img_path: string
    customer_img_path?: string
    customer_img_url?: string
    duration: number
    motion_brush: string
    asset_name: string
    asset_img_url: string
    remove_watermark: number
    nick_name: string
    avatar: string
    aspect_ratio: string
    camera_movement: string
    relation_type: number
    style: string
    template_id: number
    template_name: string
    template_thumbnail_url: string
    template_thumbnail_video_url: string
    template_thumbnail_gif_url: string
    template_i18n_json: string
    workflow_tag: string
    customer_paths?: {
        customer_img_url?: string
        customer_img_path?: string
        lip_sync_audio_url?: string
        lip_sync_audio_path?: string
        lip_sync_tts_content?: string
        sound_effect_content?: string
        lip_sync_tts_audio_path?: string
        lip_sync_tts_speaker_id?: string
        customer_video_url?: string
        customer_video_path?: string
        customer_video_duration?: number
        customer_first_frame?: string
        customer_last_frame?: string
        customer_first_frame_url?: string
        customer_last_frame_url?: string
        customer_img_urls?: string[]
        customer_img_paths?: string[]
        customer_lip_sync_audio_path?: string
    }
    platform: string
    create_mode: string
    qualities?: string[] | null
    lora_weight: number
    restyle_id: number
    restyle_prompt: string
    off_peak: number
    // added
    video_status_name: string
    video_status_final: boolean
  }[]
  next_offset: number
  total: number  
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email= "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email= "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities ===
Document URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities

<small>December 5, 2025 (May 13, 2026)</small>

---

# Video Models

## Endpoint Compatibility

| Model | [create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | [create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) | [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) | [motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control) |
|-------|:-:|:-:|:-:|:-:|
| `v6` *(default)* | ✓ | ✓ | — | — |
| `v5.6` | ✓ | ✓ | ✓ | ✓ |
| `pixverse-c1` | ✓ | ✓ | ✓ | — |
| `seedance-2.0` | ✓ | ✓ | ✓ (+2 ref videos) | — |
| `seedance-2.0-fast` | ✓ | ✓ | ✓ (+2 ref videos) | — |
| `kling-o3` | ✓ | ✓ | ✓ | — |
| `kling-v3` | ✓ | ✓ | — | — |
| `grok-imagine` | ✓ | — | — | — |
| `veo-3.1-lite` | ✓ | ✓ | — | — |
| `veo-3.1-standard` | ✓ | ✓ | — | — |
| `veo-3.1-fast` | ✓ | ✓ | — | — |
| `sora-2` | ✓ | — | — | — |
| `sora-2-pro` | ✓ | — | — | — |
| `happyhorse-1.0` | ✓ | — | — | — |

Fusion notation: `v5` uses `@pic1`/`@pic2`/`@pic3`; all other fusion-capable models use `@image1`…`@imageN` (mapped positionally to `frame_1_path`…`frame_N_path`). Seedance fusion additionally supports `@video1` / `@video2` for reference videos passed via `video_1_path` / `video_2_path`.

### Extend, upscale, modify, lipsync

Only native PixVerse models support these endpoints.

| Endpoint | `v6` | `v5` | `v5.5` | `v5.6` |
|----------|:-:|:-:|:-:|:-:|
| [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) | ✓ | ✓ | ✓ | — |
| [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) | ✓ | ✓ | ✓ | ✓ |
| [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) | — | — | ✓ | — |
| [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) | — | ✓ | — | — |

### v5 family (legacy)

v5 carries legacy-only modes — multi-frame [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition), [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync), and fusion with the original `@pic1/@pic2/@pic3` notation.

| Endpoint | `v5` | `v5.5` | `v5.6` | `v5-fast` |
|----------|:-:|:-:|:-:|:-:|
| [create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | ✓ | ✓ | ✓ | ✓ |
| [create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) | ✓ | ✓ | ✓ | — |
| [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) (2-frame) | ✓ | ✓ | ✓ | — |
| [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) (3+ frame) | ✓ | — | — | — |
| [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) | ✓ | — | ✓ | — |
| [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) | ✓ | ✓ | — | — |
| [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) | — | ✓ | — | — |
| [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) | ✓ | — | — | — |
| [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) | ✓ | ✓ | ✓ | ✓ |

`v5` accepts both `@image1`…`@imageN` (unified) and the legacy `@pic1`/`@pic2`/`@pic3` synonyms for backward compatibility.

## Quality, Duration, Aspect Ratio

| Model | Qualities | Durations | Aspect Ratios | Max ref (fusion) |
|-------|-----------|-----------|---------------|:-:|
| `v6` | 360p, 540p, 720p *(default)*, 1080p | 1-15s | 16:9, 9:16, 1:1, 4:3, 3:4 | — |
| `v5.6` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | 7 imgs |
| `v5.5` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | — |
| `v5` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | 3 imgs |
| `v5-fast` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | — |
| `pixverse-c1` | 360p, 540p, 720p, 1080p | 1-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 3:2, 2:3 | 7 imgs |
| `seedance-2.0` | 480p, 720p, 1080p | 4-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs + 2 videos |
| `seedance-2.0-fast` | 480p, 720p | 4-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs + 2 videos |
| `kling-o3` | 720p *(Std)*, 1080p *(Pro)* | 3-15s | 16:9, 1:1, 9:16 | 7 imgs |
| `kling-v3` | 720p *(Std)*, 1080p *(Pro)* | 3-15s | 16:9, 1:1, 9:16 | — |
| `grok-imagine` | 480p, 720p | 1-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 3:2, 2:3 | — |
| `veo-3.1-lite` | 720p, 1080p | 4, 6, 8 | 16:9, 9:16 | — |
| `veo-3.1-standard` | 720p, 1080p, 4K | 4, 6, 8 | 16:9, 9:16 | — |
| `veo-3.1-fast` | 720p, 1080p, 4K | 4, 6, 8 | 16:9, 9:16 | — |
| `sora-2` | 720p | 4, 8, 12 | 16:9, 9:16 | — |
| `sora-2-pro` | 720p, 1080p | 4, 8, 12 | 16:9, 9:16 | — |
| `happyhorse-1.0` | 720p, 1080p | 3-15s | 16:9, 9:16, 1:1, 4:3, 3:4 | — |

- `aspect_ratio` is required for `t2v` and `fusion`, not accepted for `i2v` or `transition` (derived from image).
- For `kling-o3` / `kling-v3`: `quality: 720p` routes to Std, `quality: 1080p` routes to Pro.
- For `veo-3.1-standard` / `veo-3.1-fast`: `quality: 1080p` requires `duration: 8`.
- **Seedance fusion** is the only path that accepts reference videos. Images go in `frame_1_path` … `frame_9_path`; videos go in `video_1_path` / `video_2_path` (referenced in the prompt as `@video1` / `@video2`). At least one reference is required. Each reference video must be 2-15s, ≤50 MB, 24-60 fps, ≤6000×6000 px; the **sum** of all reference video durations must be ≤ 15 sec.

## Audio

| Model | `audio` |
|-------|:-:|
| `v6` | toggle |
| `v5.6` | toggle |
| `v5.5` | toggle |
| `v5` | — *(use `lip_sync_tts_prompt` + `sound_effect_prompt`)* |
| `v5-fast` | — |
| `pixverse-c1` | toggle |
| `seedance-2.0` | toggle |
| `seedance-2.0-fast` | toggle |
| `kling-o3` | toggle |
| `kling-v3` | toggle |
| `grok-imagine` | rejected |
| `veo-3.1-lite` | rejected |
| `veo-3.1-standard` | always on |
| `veo-3.1-fast` | always on |
| `sora-2` | rejected |
| `sora-2-pro` | rejected |
| `happyhorse-1.0` | always on |

- `toggle` — accept `audio: true` / `false`.
- `always on` — audio generated automatically; `audio: false` is rejected.
- `rejected` — `audio` parameter is not accepted (content has no audio track or audio is handled internally).

## Native PixVerse — extra flags

`multi_shot`, `preview_mode`, `off_peak_mode`, and `seed` are supported only on native PixVerse models. Third-party models reject them.

| Model | `multi_shot` | `preview_mode` | `off_peak_mode` | `seed` |
|-------|:-:|:-:|:-:|:-:|
| `v6` | ✓ | ✓ | ✓ | ✓ |
| `v5.6` | — | ✓ | ✓ | ✓ |
| `v5.5` | — | ✓ | ✓ | ✓ |
| `v5` | — | ✓ | ✓ | ✓ |
| `v5-fast` | — | ✓ | ✓ | ✓ |
| `pixverse-c1` | — | ✓ | ✓ | ✓ |

---

# Image Models

All image models share the same endpoints: [create](/docs/api-pixverse-v2/post-pixverse-images-create), [list](/docs/api-pixverse-v2/get-pixverse-images), [get](/docs/api-pixverse-v2/get-pixverse-images-image_id), [delete](/docs/api-pixverse-v2/del-pixverse-images-image_id).

| Model | Qualities | Max Refs | Est. Time |
|-------|-----------|:--------:|:---------:|
| `qwen-image` *(default)* | 720p, 1080p | 3 | ~3s |
| `nano-banana` | 1080p | 3 | ~10s |
| `nano-banana-2` | 512p, 1080p, 1440p, 2160p | 9 | ~30s |
| `nano-banana-pro` | 1080p, 1440p, 2160p | 9 | ~60s |
| `seedream-4.0` | 1080p, 1440p, 2160p | 6 | ~10s |
| `seedream-4.5` | 1440p, 2160p | 6 | ~15s |
| `seedream-5.0-lite` | 1440p, 1800p | 6 | ~30s |
| `kling-3.0` | 1080p, 1440p | 1 | ~15s |
| `kling-o3` | 1080p, 1440p, 2160p | 1 | ~20s |
| `gpt-image-2.0` | 1080p, 1440p, 2160p | 9 | ~30s |

- **`create_count`**: 1-4 (default 1).
- **`detail_level`** (`gpt-image-2.0` only, **required**): `low`, `medium`, `high`. Rejected for all other models. Affects credit cost (low = 0.5×, medium = 1×, high = 2× of the per-quality base).

### Aspect ratios

Each model accepts its own list. If `aspect_ratio` is omitted, the **default** (first column) is used. Passing a value not in the model's row is rejected with **400**.

| Models | Default | Accepted `aspect_ratio` values |
|--------|:-------:|-------------------------------|
| `nano-banana`, `nano-banana-2`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` |
| `qwen-image` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` |
| `kling-o3`, `kling-3.0` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9` |
| `gpt-image-2.0` | `1:1` | `1:1`, `1:2`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `2:1`, `21:9` |

## Unlimited Image Generation (Relax Mode)

Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models:

| Plan | Price | Unlimited Models |
|------|:-----:|:-----------------|
| Pro | $30/m | `qwen-image` |
| Premium | $60/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `seedream-4.0` |
| Ultra | $199/m | all 10 image models |

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email
## Create or update PixVerse API account configuration
<small>December 6, 2024 (March 11, 2025)</small>

---
See [Setup PixVerse](/docs/start-here/setup-pixverse) for details.     

For your convenience, you can specify your PixVerse configuration values under your account. If you specify multiple PixVerse accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to PixVerse.
> **https://api.useapi.net/v2/pixverse/accounts/`email`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Required PixVerse account email",
    "password": "Required PixVerse account password",
    "maxJobs": 1-8,
    "token": "Optional PixVerse token",
}
```
- `email` and `password` are **required**. Please see [Setup PixVerse](/docs/start-here/setup-pixverse) for details. 

- `maxJobs` is **required**.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

- `token` is optional and should only be used for development or debugging purposes. See [details](/docs/start-here/setup-pixverse#optional-configure-pixverse-api-to-use-the-current-pixverseai-session).   
  **Important:** When creating an account, leave the token field empty. Only add it after the account has been created, and only if you truly need it.

##### Responses 

**201**
**201 Created** 

```json
{
  "email": "<account email>",
  "password": "…secured…",  
  "maxJobs": 3,
  "jwt": {
    "AccountId": 66778899,
    "ExpireTime": 123456789,
    "ExpireTimeUTC": "2025-01-01T12:13:14.000Z",
    "Username": "<username>",
    "token": "abc…secured…cde"
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "<Error message>",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string
  password: string
  maxJobs: number
  jwt: {
    AccountId: number
    ExpireTime: number
    ExpireTimeUTC: string
    Username: string
    token: string
  }  
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/pixverse/accounts/<email> \
     -d '{"email": "…", "password": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const email = "PixVerse account email";      
const password = "PixVerse account password";      
const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; 
const api_token = "API token";
const maxJobs = 3;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  email, password, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
email = "PixVerse account email"
password = "PixVerse account password"
apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}" 
api_token = "API token"
maxJobs = 3
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "email": f"{email}",
    "password": f"{password}", 
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files
## Upload image, video or audio file
<small>December 6, 2024 (April 5, 2026)</small>

---

Upload an image, video, or audio file up to 5GB in size. Files uploaded to one PixVerse.ai account can be accessed from any other PixVerse.ai account just by referencing the `id` (image) or `path` (video/audio) so keep that in mind.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v2/pixverse/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type        | File Extension |
| ------------------- | -------------- |
| image/png           | png            |
| image/jpeg          | jpeg           |
| image/gif           | gif            |
| image/webp          | webp           |
| video/mp4           | mp4            |
| video/quicktime     | mov            |
| video/3gpp          | 3gp            |
| video/x-matroska    | mkv            |
| video/x-flv         | flv            |
| video/mpeg          | mpeg           |
| video/MP2T          | ts             |
| video/x-msvideo     | avi            |
| video/x-motion-jpeg | mjpeg          |
| video/webm          | webm           |
| video/ogg           | ogv            |
| audio/wav           | wav            |
| audio/wave          | wav            |
| audio/mpeg          | mp3            |

**NOTE** We took a guess on supported video and audio types and only tested the most popular ones.

**Image resolution limit:** PixVerse does not support images larger than ~2K resolution. If your image exceeds 2048px on either dimension, downscale it to 2K or 1080p before uploading. Oversized images may fail silently or produce unexpected results.

##### Query Parameters

- `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

The image upload response contains a `id` that you can use to reference the uploaded image file:

```json
{
    "result": [
        {
            "id": 123456,
            "url": "<file url>",
            "path": "<file path>",
            "size": 112233,
            "name": "<file name>",
            "category": 0,
            "err_msg": ""
        }
    ]
}
```

The video/audio upload response contains a `path` that you can use to reference the uploaded video/audio file:

```json
{
    "path": "<file path>",
    "url": "<file url>"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    url: string
    path: string
    result: {
        id: number
        url: string
        path: string
        size: number
        name: string
        category: number
        err_msg: string
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v2/pixverse/files/?email=email" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: image/jpeg" \
  --data-binary /path/to/your/image.jpeg
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured account email"; 
const apiUrl = `https://api.useapi.net/v2/pixverse/files/?email=${email}`; 
let blob;
/*
    // Example 1: Fetch image from URL
    const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
    const responseImage = await fetch(imageUrl);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load image from local file (Blob)
    const fsp = require('fs').promises;
    const imageFileName = "./cat.png";
    blob = new Blob([await fsp.readFile(imageFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="image-file" type="file"> 
    const imageFile = document.getElementById(`image-file`);
    if (imageFile.files[0])
        blob = imageFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured account email"
apiUrl = f"https://api.useapi.net/v2/pixverse/files/?email={email}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# file_content = response_image.content

# # Example 2: Load image from local file
# image_file_path = "./image.jpg"
# with open(image_file_path, 'rb') as image_file:
#     file_content = image_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-create ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-create
## Create an image using a text prompt
## Table of contents
<small>March 9, 2026 (May 13, 2026)</small>
---

Use [pixverse.ai](https://app.pixverse.ai) account to generate images. Supports text-to-image (t2i) and image-to-image (i2i) with reference images uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

##### Model Comparison Matrix

| Model | Qualities | Ref Images | Est. Time |
|:------|:----------|:-----------|:---------|
| `qwen-image` *(default)* | 720p, 1080p | 1-3 via `image_path_1`…`3` | ~3s |
| `nano-banana` *<sup>\*</sup>* | 1080p | 1-3 via `image_path_1`…`3` | ~10s |
| `nano-banana-2` *<sup>\*</sup>* | 512p, 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~30s |
| `nano-banana-pro` *<sup>\*</sup>* | 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~60s |
| `seedream-4.0` | 1080p, 1440p, 2160p | 1-6 via `image_path_1`…`6` | ~10s |
| `seedream-4.5` | 1440p, 2160p | 1-6 via `image_path_1`…`6` | ~15s |
| `seedream-5.0-lite` | 1440p, 1800p | 1-6 via `image_path_1`…`6` | ~30s |
| `kling-3.0` | 1080p, 1440p | 1 via `image_path_1` | ~15s |
| `kling-o3` | 1080p, 1440p, 2160p | 1 via `image_path_1` | ~20s |
| `gpt-image-2.0` | 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~30s |

<sup>\*</sup> Nano Banana / Nano Banana 2 / Nano Banana Pro have less restrictive content moderation and can use photos of minors or recognizable people as reference images. Use responsibly and in compliance with applicable laws.

##### Aspect Ratios

Each model accepts its own list. If `aspect_ratio` is omitted, the **default** (first column) is used. Passing a value not in the model's row is rejected with **400**.

| Models | Default | Accepted `aspect_ratio` values |
|--------|:-------:|-------------------------------|
| `nano-banana`, `nano-banana-2`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` |
| `qwen-image` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` |
| `kling-o3`, `kling-3.0` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9` |
| `gpt-image-2.0` | `1:1` | `1:1`, `1:2`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `2:1`, `21:9` |

`gpt-image-2.0` also requires the `detail_level` parameter (`low`, `medium`, or `high`) — affects credit cost (see credits estimator below).

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Credits are charged per image. Actual costs may change, see [pixverse.ai](https://app.pixverse.ai/subscribe) for current pricing.

| Model | Quality | Credits per image | Quantity |
|:------|:--------|:-----------------:|:---------|
| qwen-image | 720p | 5 | 1-4 |
| qwen-image | 1080p | 10 | 1-4 |
| seedream-4.0 | all | 10 | 1-4 |
| seedream-4.5 | all | 10 | 1-4 |
| nano-banana | 1080p | 15 | 1-4 |
| seedream-5.0-lite | all | 15 | 1-4 |
| nano-banana-2 | 512p | 16 | 1-4 |
| nano-banana-2 | 1080p | 25 | 1-4 |
| nano-banana-2 | 1440p | 40 | 1-4 |
| nano-banana-2 | 2160p | 60 | 1-4 |
| nano-banana-pro | 1080p, 1440p | 50 | 1-4 |
| nano-banana-pro | 2160p | 90 | 1-4 |
| kling-3.0 | 1080p, 1440p | 10 | 1-4 |
| kling-o3 | 1080p, 1440p | 10 | 1-4 |
| kling-o3 | 2160p | 20 | 1-4 |
| gpt-image-2.0 | 1080p (low / medium / high) | 15 / 30 / 60 | 1-4 |
| gpt-image-2.0 | 1440p (low / medium / high) | 30 / 60 / 120 | 1-4 |
| gpt-image-2.0 | 2160p (low / medium / high) | 45 / 90 / 180 | 1-4 |

</details>

##### Unlimited Image Generation (Relax Mode)

Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models:

| Plan | Price | Unlimited Models |
|------|:-----:|:-----------------|
| Pro | $30/m | `qwen-image` |
| Premium | $60/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `seedream-4.0` |
| Ultra | $199/m | all 10 image models |

To retrieve generated image(s), use:
* [GET images/`imageId`](/docs/api-pixverse-v2/get-pixverse-images-image_id)

To delete a generated image, use:
* [DEL images/`imageId`](/docs/api-pixverse-v2/del-pixverse-images-image_id)
> **https://api.useapi.net/v2/pixverse/images/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "Required text prompt",
    "model": "seedream-4.0",
    "quality": "1080p",
    "aspect_ratio": "auto",
    "detail_level": "medium",
    "create_count": 1,
    "seed": 654321,
    "image_path_1": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```

##### Parameters

- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).

- `prompt` is **required**, describe your image.
  Maximum length 5,000 characters.

- `model` is optional. Default: `qwen-image`. See [Model Comparison Matrix](#model-comparison-matrix) for the full list and per-model notes.

- `quality` is optional, model-specific. Defaults to the model's first listed value. See [Model Comparison Matrix](#model-comparison-matrix) for per-model qualities.

- `aspect_ratio` is optional. Each model accepts its own list — see [Aspect Ratios](#aspect-ratios) above. If omitted, the model's default is used. Passing a value not in the model's row is rejected with **400**.

- `detail_level` is **required** for `gpt-image-2.0` and rejected for all other models.
  Supported values: `low`, `medium`, `high`. Affects credit cost (low = 0.5×, medium = 1×, high = 2× per quality — see credits estimator).

- `create_count` is optional. Number of images to generate per request.
  Supported range: 1…4, default 1.

- `seed` is optional.
  Valid range 0…2147483647.

- `image_path_1` through `image_path_9` are optional. Reference image file paths uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files) for image-to-image (i2i) generation.
  Reference images must be provided sequentially — `image_path_2` requires `image_path_1`, etc.
  Maximum number of references depends on the model (see [Model Comparison Matrix](#model-comparison-matrix)).

- `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse image is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse image response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.
  Valid range: 1…8

##### Responses

**200**
**200 OK**

Use returned `image_id` or values from `success_ids` array to retrieve image status and results using [GET images/`imageId`](/docs/api-pixverse-v2/get-pixverse-images-image_id). Check `image_status_name` for `COMPLETED` and `image_url` for the generated image link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with image progress updates until the image is complete or fails.

```json
{
    "image_id": "user:<userid>-pixverse:<email>-image:<number>",
    "success_ids": [
        "user:<userid>-pixverse:<email>-image:<id_1>",
        "user:<userid>-pixverse:<email>-image:<id_2>"
    ],
    "success_count": 2,
    "fail_count": 0,
    "total_count": 2,
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [images/create](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error":
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message**

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error":
    "Your PixVerse account has pending error."
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
    image_id: string
    success_ids: string[]
    success_count: number
    fail_count: number
    total_count: number
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/images/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"
apiUrl = f"https://api.useapi.net/v2/pixverse/images/create"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4 ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4
## Create video using first and last frames
<small>March 31, 2025 (April 20, 2026)</small>

---

This endpoint creates a **2-frame transition** (first frame → last frame) and supports:
- Native PixVerse: `v5.6` (default), `v5.5`, `v5`, `v5-fast`, `pixverse-c1`
- Third-party: `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`

See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model quality and duration constraints.

To upload prompt image use [POST /files](/docs/api-pixverse-v2/post-pixverse-files).
> **https://api.useapi.net/v2/pixverse/videos/create-frames**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "Optional text prompt",
    "first_frame_path": "upload/7d16f-eed2-a8f4-cef8-aa44-72807n313.jpeg",
    "last_frame_path": "upload/e7484a28-6efd-174d-7c02-316ef1a5d.jpeg",
    "duration": 8,
    "quality": "1080p",
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional. Default: `v5.6`.
  Supported values — native PixVerse: `v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1`. Third-party: `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model constraints.

- `prompt` is optional, describe your video.  
  Maximum length 5,000 characters.

- `first_frame_path` is **required**, provide path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files).

- `last_frame_path` is **required**, provide path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files).

- `duration` is optional. Video duration in seconds — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). Default: `5`.

- `quality` is optional. Video quality — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities).
  **Kling note:** `kling-o3` / `kling-v3` — `quality: 720p` routes to Standard tier, `quality: 1080p` routes to Pro tier.

- `audio` is optional. Behavior depends on the model:
  * **Toggle** (`true`/`false`) — `v5.5`, `v5.6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`.
  * **Always on** (cannot disable) — `veo-3.1-standard`, `veo-3.1-fast`.
  * **Not supported** (reject if supplied) — `v5`, `v5-fast`, `veo-3.1-lite`.
  Supported values: not specified (default), `false`, `true`.

- `aspect_ratio` is **not accepted** — transition derives aspect ratio from the first frame.

- `preview_mode` is optional. Set to `true` for fast preview generation (lower quality, faster results).
  Preview videos can later be upscaled via [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale).
  Supported values: `false` (default), `true`.

- `auto_sound` is optional (v5 only). Set to `true` to generate videos with sound.
  Supported values: not specified (default), `false`, `true`.

- `sound_effect_prompt` is optional (v5 only), describe the sound eg "the sound of waves hitting the shore".

- `lip_sync_tts_prompt` is optional (v5 only), enter character lines.
  Maximum length 140 characters.

- `lip_sync_tts_speaker_id` is optional (v5 only), specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices).

- `seed` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag.
  Valid range 1…2147483647. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  
  
- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/create-frames](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/create-frames" \
     -d '{"prompt": "…", "first_frame_path": "…", "last_frame_path": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";  
const first_frame_path = "provide path of uploaded first image via POST /files";    
const last_frame_path = "provide path of uploaded last image via POST /files";    
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-frames`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt, first_frame_path, last_frame_path
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
first_frame_path = "provide path of uploaded first image via POST /files"    
last_frame_path = "provide path of uploaded last image via POST /files"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-frames" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}",
    "first_frame_path": f"{first_frame_path}",
    "last_frame_path": f"{last_frame_path}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-fusion ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-fusion

## Create video using image fusion
<small>May 16, 2025 (May 13, 2026)</small>

---

Upload multiple reference frames and describe the content you want to create. Also known as **Reference mode** or **video-reference**.

**Supported models** (see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for max images per model):
- Native PixVerse: `v5` (up to 3), `v5.6` (up to 7), `pixverse-c1` (up to 7)
- Third-party: `seedance-2.0` (up to 9 + 2 ref videos), `seedance-2.0-fast` (up to 9 + 2 ref videos), `kling-o3` (up to 7)

All models use `@image1`…`@imageN` in the prompt, mapped positionally to `frame_1_path`…`frame_N_path`. `v5` also accepts the legacy `@pic1`/`@pic2`/`@pic3` synonyms.

`seedance-2.0` and `seedance-2.0-fast` additionally accept up to two **reference videos** via `video_1_path` / `video_2_path`, referenced in the prompt as `@video1` / `@video2`. Use ref videos to drive motion, camera moves, or rhythm onto your character image.

To upload prompt images and videos use [POST /files](/docs/api-pixverse-v2/post-pixverse-files).
> **https://api.useapi.net/v2/pixverse/videos/create-fusion**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "model": "pixverse-c1",
    "prompt": "A dog @image1 and a cat @image2 traveling together in the car @image3",
    "frame_1_path": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png",
    "frame_2_path": "upload/7b45d27f-301c-4d18-a2a1-f8bc3672e6a9.png",
    "frame_3_path": "upload/f8bc3672e6a9-301c-4d18-a2a1-7b45d27f.png",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "audio": true,
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference here",
    "off_peak_mode": true
}
```
- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional. Default: `pixverse-c1`.
  Supported values: `v5`, `v5.6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`.

- `prompt` is **required**, describe your video.  
  Maximum length 5,000 characters. Use `@image1`, `@image2`, … `@imageN` in the prompt to reference `frame_1_path`…`frame_N_path` by index. `v5` also accepts the legacy `@pic1`/`@pic2`/`@pic3` synonyms for backward compatibility.

- `frame_1_path` is **required**, provide the path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_2_path` through `frame_9_path` are optional. Max accepted depends on the model:
  * `pixverse-c1` — up to **7** (`frame_1_path`…`frame_7_path`)
  * `seedance-2.0`, `seedance-2.0-fast` — up to **9**
  * `kling-o3` — up to **7**
  * `v5` — up to **3** (`frame_1_path`, `frame_2_path`, `frame_3_path`)

  Frames must be provided sequentially — `frame_3_path` requires `frame_2_path`, etc.

- `video_1_path`, `video_2_path` are optional and only supported for `seedance-2.0` / `seedance-2.0-fast`. Provide the path of an uploaded video via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Reference them in the prompt as `@video1` / `@video2`. Must be sequential — `video_2_path` requires `video_1_path`.

  **Reference video limits** (enforced by PixVerse upstream):
  * Each video: **2–15 sec**, **≤ 50 MB**, **24–60 fps**, max dimensions **6000 × 6000 px**
  * Sum of all reference video durations: **≤ 15 sec**

- `duration` is optional. Video duration in seconds — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). Default: `5`.

- `quality` is optional. Video quality — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities).

- `aspect_ratio` is optional, default `16:9`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model supported values.

- `audio` is optional (where supported by the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities)). Set to `true` to enable integrated audio.
  Supported values: `false` (default), `true`.

- `seed` is optional.   
  Valid range 1…999999. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  
  
- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/create-fusion](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/create-fusion" \
     -d '{"prompt": "A dog @image1 and a cat @image2 traveling together", "frame_1_path": "…", "frame_2_path": "…"}'
```

**JavaScript**
``` javascript
const prompt = "A dog @image1 and a cat @image2 traveling together";  
const frame_1_path = "provide path of uploaded first image via POST /files";    
const frame_2_path = "provide path of uploaded last image via POST /files";    
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-fusion`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt, frame_1_path, frame_2_path
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "A dog @image1 and a cat @image2 traveling together"      
frame_1_path = "provide path of uploaded first image via POST /files"    
frame_2_path = "provide path of uploaded last image via POST /files"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-fusion" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}",
    "frame_1_path": f"{frame_1_path}",
    "frame_2_path": f"{frame_2_path}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-transition ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-transition
## Create transition video
<small>August 29, 2025 (January 27, 2026)</small>

---

This endpoint creates multi-frame transition videos with up to 7 frames and customizable transition durations between frames.

To upload frame images use [POST files](/docs/api-pixverse-v2/post-pixverse-files).
> **https://api.useapi.net/v2/pixverse/videos/create-transition**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "quality": "540p",
    "seed": 123456789,
    "frame_1_path": "upload/scene1.jpg",
    "frame_2_path": "upload/scene2.jpg",
    "frame_3_path": "upload/scene3.jpg",
    "duration_1_to_2": "3",
    "duration_2_to_3": "2",
    "prompt_1_to_2": "Smooth fade between scenes",
    "prompt_2_to_3": "Quick transition",
    "lip_sync_tts_prompt": "Optional TTS narration",
    "lip_sync_tts_speaker_id": "speaker_001",
    "auto_sound": true,
    "sound_effect_prompt": "Ambient background music",
    "off_peak_mode": false,
    "maxJobs": 1,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```

- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional. Model availability depends on frame count:
  - **2-frame mode** (frame_1 + frame_2 only): Supports `v5.6` (default), `v5.5`, and `v5`.
    - v5.5/v5.6: Use `audio` parameter for sound.
    - v5: Use `lip_sync_tts_prompt` and `sound_effect_prompt` for audio.
  - **3+ frame mode** (3-7 frames): Only `v5` supported (default). Use `lip_sync_tts_prompt` and `sound_effect_prompt` for audio.

  Using incompatible parameters for the model returns error 400.

  See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for feature differences.

- `quality` is optional. Video quality.
  Supported values: `1080p`, `720p`, `540p` (default), `360p`.

- `seed` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag.
  Valid range 1…2147483647. 

- `frame_1_path` is **required**, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_2_path` is **required**, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_3_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_4_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_5_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_6_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `frame_7_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files).

- `duration_1_to_2` is optional. Transition duration from frame 1 to frame 2 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `duration_2_to_3` is optional. Transition duration from frame 2 to frame 3 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `duration_3_to_4` is optional. Transition duration from frame 3 to frame 4 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `duration_4_to_5` is optional. Transition duration from frame 4 to frame 5 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `duration_5_to_6` is optional. Transition duration from frame 5 to frame 6 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `duration_6_to_7` is optional. Transition duration from frame 6 to frame 7 in seconds.  
  Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.

- `prompt_1_to_2` is optional, describe transition from frame 1 to frame 2.

- `prompt_2_to_3` is optional, describe transition from frame 2 to frame 3.

- `prompt_3_to_4` is optional, describe transition from frame 3 to frame 4.

- `prompt_4_to_5` is optional, describe transition from frame 4 to frame 5.

- `prompt_5_to_6` is optional, describe transition from frame 5 to frame 6.

- `prompt_6_to_7` is optional, describe transition from frame 6 to frame 7.

- `audio` is optional (**2-frame mode only**, v5.5/v5.6 only). Set to `true` to enable integrated native audio generation.
  v5.5/v5.6 generates voice, lip sync, and background music together with the video. Not supported with v5 model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities).
  Supported values: not specified (default), `false`, `true`.

- `preview_mode` is optional. Set to `true` for fast preview generation (lower quality, faster results).
  Preview videos can later be upscaled via [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale).
  Supported values: `false` (default), `true`.

- `auto_sound` is optional (**v5 model only**). Set to `true` to generate videos with sound.
  Supported values: not specified (default), `false`, `true`.

- `sound_effect_prompt` is optional (**v5 model only**), describe the sound eg "epic adventure music".
  Maximum length 140 characters.

- `lip_sync_tts_prompt` is optional (**v5 model only**), enter character lines.
  Maximum length 140 characters.

- `lip_sync_tts_speaker_id` is optional (**v5 model only**), specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices).

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  

- `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.   
  Valid range: 1…8    

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/create-transition](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/create-transition" \
     -d '{"frame_1_path": "…", "frame_2_path": "…"}'
```

**JavaScript**
``` javascript
const frame_1_path = "provide path of uploaded first image via POST /files";    
const frame_2_path = "provide path of uploaded second image via POST /files";    
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-transition`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  frame_1_path, frame_2_path
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
frame_1_path = "provide path of uploaded first image via POST /files"    
frame_2_path = "provide path of uploaded second image via POST /files"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-transition" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "frame_1_path": f"{frame_1_path}",
    "frame_2_path": f"{frame_2_path}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4 ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4
## Create video
<small>March 24, 2025 (May 12, 2026)</small>

---

This endpoint supports both **text-to-video (t2v)** and **image-to-video (i2v)** modes.

**Supported models** (see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model constraints):
- Native PixVerse: `v6` (default), `v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1`
- Third-party: `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`, `grok-imagine`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `sora-2`, `sora-2-pro`, `happyhorse-1.0`

For dedicated image generation, see [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create).

To upload prompt image use [POST files](/docs/api-pixverse-v2/post-pixverse-files).
> **https://api.useapi.net/v2/pixverse/videos/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body

**Text-to-video**
```json
{
    "model": "v6",
    "prompt": "A red panda eating bamboo in a misty forest",
    "duration": 5,
    "quality": "720p",
    "aspect_ratio": "16:9"
}
```

**Image-to-video**
```json
{
    "model": "v6",
    "prompt": "The subject turns and smiles at camera",
    "first_frame_path": "upload/eb20c63d-…png",
    "duration": 5,
    "quality": "720p"
}
```

**Template (1–2 inputs)**
```json
{
    "template_id": 326733946317888,
    "first_frame_path": "upload/a-…jpeg",
    "last_frame_path": "upload/b-…jpeg"
}
```

**Template (3–5 inputs)**
```json
{
    "template_id": 384628677917440,
    "prompt": "A warm family reunion in a sunlit backyard.",
    "frame_1_path": "upload/a-…jpeg",
    "frame_2_path": "upload/b-…jpeg",
    "frame_3_path": "upload/c-…jpeg",
    "frame_4_path": "upload/d-…jpeg",
    "frame_5_path": "upload/e-…jpeg"
}
```

###### Parameters

- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional. Default: `v6`.
  Supported values — native PixVerse: `v6`, `v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1`. Third-party: `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3`, `grok-imagine`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `sora-2`, `sora-2-pro`, `happyhorse-1.0`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model quality, duration, and aspect-ratio constraints.
  **Ignored when `template_id` is set** — see [notes](#input-image-paths-and-templates).

- `prompt` is optional, describe your video.  
  Maximum length 5,000 characters.

- `first_frame_path`, `last_frame_path`, `frame_1_path`, `frame_2_path`, `frame_3_path`, `frame_4_path`, `frame_5_path` are optional input image paths. Upload images via [POST /files](/docs/api-pixverse-v2/post-pixverse-files) first and use the returned `path` value. Two interchangeable forms exist for providing image paths and the count rules depend on `effect_type` — see [notes](#input-image-paths-and-templates) for full rules.

- `template_id` is optional, effect template id from [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects). When set, the template controls model/duration/quality — see [notes](#input-image-paths-and-templates).

- `duration` is optional. Video duration in seconds — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). Default: `5`. **Ignored when `template_id` is set.**

- `quality` is optional. Video quality — accepted values depend on the model. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). For `kling-o3` and `kling-v3`, `quality: 720p` routes to the Standard upstream tier and `quality: 1080p` routes to the Pro tier. **When `template_id` is set**, must be one of the template's `qualities` (see [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects)); defaults to the first entry if omitted.

- `aspect_ratio` is optional, **required for t2v** (no image), **not accepted for i2v** (derived from input image). See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model supported values.

- `auto_sound` is optional. Set to `true` to generate videos with sound or `false` to explicitly remove the default effect sound.  
  Supported values: not specified (default), `false`, `true`.

- `sound_effect_prompt` is optional, describe the sound eg "the sound of waves hitting the shore".

- `lip_sync_tts_prompt` is optional, enter character lines.   
  Maximum length 140 characters.

- `lip_sync_tts_speaker_id` is optional, specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices).

- `audio` is optional. Supported values: `false` (default), `true`. Behavior depends on the model:

  | Behavior | Models | What it means |
  |---|---|---|
  | Toggle | `v5.5`, `v5.6`, `v6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `kling-o3`, `kling-v3` | `true` or `false` accepted; enables integrated audio generation |
  | Always on | `veo-3.1-standard`, `veo-3.1-fast`, `happyhorse-1.0` | Audio generated automatically; setting `false` is rejected |
  | Not supported | `grok-imagine`, `veo-3.1-lite`, `sora-2`, `sora-2-pro` | Passing any value is rejected |

- `multi_shot` is optional. **v6 only.** Set to `true` to enable multi-shot storytelling — the AI generates videos with multiple camera angles and scene cuts rather than a single continuous shot.
  Supported values: `false` (default), `true`.

- `preview_mode` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Set to `true` to generate a fast preview at lower quality at **20% off** credits. Use [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) to upscale the preview to full quality.
  Supported values: `false` (default), `true`.

- `seed` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag.
  Valid range 1…2147483647. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  

- `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.   
  Valid range: 1…8    

###### Input image paths and templates

| `effect_type` | Input count | Form to use |
|---|---|---|
| _(no `template_id`)_ | 0 or 1 | `first_frame_path` (or `frame_1_path`) — omit for text-to-video |
| `"1"` | exactly 1 | `first_frame_path` (or `frame_1_path`) |
| `"2"` | exactly 2 | `first_frame_path` + `last_frame_path` (or `frame_1_path` + `frame_2_path`) |
| `"3"` | 2 to 3 | `frame_1_path` … up to `frame_3_path` |
| `"4"` | 2 to 4 | `frame_1_path` … up to `frame_4_path` |
| `"5"` | 2 to 5 | `frame_1_path` … up to `frame_5_path` |

Never mix `first_frame_path`/`last_frame_path` with `frame_N_path`. In the numbered form, fill slots in order — no `frame_3_path` without `frame_2_path`.

When `template_id` is set, the template controls `model`, `duration`, and `quality` — skip those parameters. Anything you pass for `model` or `duration` is ignored, and `quality` (if set) must be one the template allows. Image templates (`template_type: 2`) produce a 1-second still — the response carries `image_id` instead of `video_id`.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` or `image_id` to retrieve video status and results using [GET videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/create](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    image_id: string // When image template_id is used (template_type: 2)
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-extend-v4 ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-extend-v4
## Extend video 
<small>March 31, 2025 (April 5, 2026)</small>

---

This endpoint uses PixVerse models `v6`, `v5.5`, and `v5`. Default: `v6`.

* Extend a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to extend.
> **https://api.useapi.net/v2/pixverse/videos/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "Optional text prompt",
    "video_id": "Optional video_id",
    "duration": 5,
    "quality": "720p",
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional.    
  Supported values: `v6` (default), `v5.5`, and `v5`.

- `prompt` is optional, describe your video.    
  Maximum length 5,000 characters.
  
- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to extend.

- `duration` is optional. Extend duration in seconds.
  Supported values: `1` through `15` for v6, `1` through `10` for older models. Default: `5`. Note: pre-v6 models limit 1080p to 8 seconds maximum.

- `quality` is optional. Video quality.  
  Supported values: `1080p`, `720p` (default for v6), `540p` (default for v5.x), `360p`.

- `audio` is optional. **v6 only.** Set to `true` to enable integrated audio generation on the extended segment.
  Supported values: `false` (default), `true`.

- `seed` is optional.     
  Valid range 1…2147483647. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  
 
- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.    
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.    
  Valid range: 1…8      
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/extend](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/extend" \
     -d '{"prompt": "…", "video_id": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const video_id = "video_id";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/extend`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt, video_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
video_id = "video_id"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/extend" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}",
    "video_id": f"{video_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-lipsync ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-lipsync
## Lip sync video
<small>December 6, 2024 (January 27, 2026)</small>

---

* This endpoint uses PixVerse model `v5` only. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for details.

* Lip sync a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to lip sync.

* Upload the audio track using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the audio you want to use for lip sync.
> **https://api.useapi.net/v2/pixverse/videos/lipsync**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "video_id": "Optional video_id",
    "audio_path": "Optional audio track path",
    "prompt": "Optional text prompt",
    "speaker_id": 12345,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `email` is optional, if not specified API will use account specified by `video_id` (if provided), otherwise randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to lip sync.

- `audio_path` is optional, upload the audio track using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the audio you want to use for lip sync. Maximum length of the audio track should not exceed 60 seconds. Generation will fail if you attempt to provide a sound clip longer than that.  

- `prompt` is optional, provide text you want to use for lip sync.
  Maximum length 200 characters.

- `speaker_id` is optional, to retrieve `speaker_id` see [GET /videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices).

- `original_sound_switch` is optional, set to `true` if you want to keep the original soundtrack of the video and extend it with the provided sound clip or generated audio.  

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  
  
- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/lipsync](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/lipsync" \
     -d '{"audio_path": "…", "video_id": "…"}'
```

**JavaScript**
``` javascript
const audio_path = "audio_path";      
const video_id = "video_id";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/lipsync`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  audio_path, video_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
audio_path = "audio_path"      
video_id = "video_id"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/lipsync" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "audio_path": f"{audio_path}",
    "video_id": f"{video_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-modify ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-modify
## Modify video
<small>January 26, 2026</small>

---

This endpoint uses PixVerse model `v5.5`.  
Modify video content based on your prompt.

* Modify a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to modify.
> **https://api.useapi.net/v2/pixverse/videos/modify**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "Required modification prompt",
    "video_id": "Optional video_id",
    "quality": "540p",
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).

- `model` is optional.  
  Supported values: `v5.5` (default).

- `prompt` is **required**, describe the modification you want to apply.  
  Maximum length 5,000 characters.

- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to modify.

- `quality` is optional. Video quality.  
  Supported values: `720p`, `540p` (default), `360p`.

- `seed` is optional.  
  Valid range 1…2147483647.

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.

- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses

**200**
**200 OK**

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message or no masks detected.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

```json
{
  "error": "No masks detected in video frame"
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/modify](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error":
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message**

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error":
    "Your PixVerse account has pending error."
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/modify" \
     -d '{"prompt": "change the outfit to red dress", "video_id": "…"}'
```

**JavaScript**
``` javascript
const prompt = "change the outfit to red dress";
const video_id = "video_id";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/modify`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  prompt, video_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "change the outfit to red dress"
video_id = "video_id"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/modify"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}",
    "video_id": f"{video_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-motion-control ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-motion-control
## Motion Control
<small>May 13, 2026</small>

---

Drive a character image with motion extracted from a reference video. Upload a portrait (the character) and a short motion clip — PixVerse animates the character following the motion of the clip. Useful for transferring dance moves, gestures, or full-body action onto a still image.

* Upload the character image and the motion video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files).
* PixVerse validates the character image before submission — if it cannot detect a clear person or animal subject, the request is rejected with **422**.
* This endpoint does **not** accept a prompt — motion comes entirely from the reference video.
> **https://api.useapi.net/v2/pixverse/videos/motion-control**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "frame_1_path": "upload/a1b2c3d4-1111-2222-3333-character000001.webp",
    "video_1_path": "upload/e5f6a7b8-4444-5555-6666-motionvideo0001.mp4",
    "quality": "720p",
    "off_peak_mode": false,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference here"
}
```

- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).

- `frame_1_path` is **required** — character image path uploaded via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Must contain a clear subject (person or animal); ambiguous or empty images will be rejected with **422**.

- `video_1_path` is **required** — motion reference video path uploaded via [POST /files](/docs/api-pixverse-v2/post-pixverse-files).

  **Motion video limits** (enforced by PixVerse upstream):
  * Duration: **1–30 sec**
  * File size: **≤ 50 MB**
  * Dimensions: **≤ 1920 × 1920 px**

- `model` is optional. Currently only one engine is supported.
  Supported values: `v5.6` (default).

- `quality` is optional. Video quality.
  Supported values: `360p`, `540p`, `720p` (default).

- `off_peak_mode` is optional. Set to `true` to generate during low-demand periods at a reduced credit cost. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.
  Supported values: `false` (default), `true`.

- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.
  Valid range: 1…8
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses

**200**
**200 OK**

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Character image was rejected — PixVerse could not detect a clear person or animal subject.

```json
{
  "error": "Character image was rejected — upload a clear photo with a person or animal as the subject"
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

```json
{
    "error":
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message**

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error":
    "Your PixVerse account has pending error."
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/motion-control" \
     -d '{"frame_1_path": "upload/…webp", "video_1_path": "upload/…mp4", "quality": "720p"}'
```

**JavaScript**
``` javascript
const frame_1_path = "provide path of uploaded character image via POST /files";
const video_1_path = "provide path of uploaded motion video via POST /files";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/motion-control`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  frame_1_path, video_1_path, quality: '720p'
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
frame_1_path = "provide path of uploaded character image via POST /files"
video_1_path = "provide path of uploaded motion video via POST /files"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/motion-control"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "frame_1_path": f"{frame_1_path}",
    "video_1_path": f"{video_1_path}",
    "quality": "720p"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-restyle-v4 ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-restyle-v4
## Restyle video 
<small>March 31, 2025 (January 27, 2026)</small>

<span class="required-input-field"><b>PixVerse website no longer supports Restyle. This endpoint no loner available.</b></span>

---

> [v5 release endpoint changes](/docs/changelog#august-29-2025)

This endpoint uses PixVerse model `v5`.

* Restyle a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to restyle.
> **https://api.useapi.net/v2/pixverse/videos/restyle**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "Required text prompt",
    "video_id": "Optional video_id",
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional.
  Supported values: `v5` (default).

- `prompt` is optional, describe the desired style for your video.  
  Maximum length 5,000 characters.
  
- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to restyle.

- `restyle_id` is optional, retrieve supported styles using [GET videos/restyles](/docs/api-pixverse-v2/get-pixverse-videos-restyles). 

- `seed` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag.
  Valid range 1…2147483647. 
 
- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results.  
  Supported values: `false` (default), `true`.  

- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/restyle](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/restyle" \
     -d '{"prompt": "…", "video_id": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const video_id = "video_id";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/restyle`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt, video_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
video_id = "video_id"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/restyle" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}",
    "video_id": f"{video_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-upscale ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-upscale
## Upscale to 4K
<small>December 6, 2024</small>

---
> **https://api.useapi.net/v2/pixverse/videos/upscale**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "video_id": "Required video_id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```
- `video_id` is **required**, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos).
 
- `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used.  
  Valid range: 1…8  
  It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan.

##### Responses 

**200**
**200 OK** 

Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link.

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits.

```json
{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new [videos/upscale](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": 
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}
```
2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "Reached the limit for concurrent generations."
}
```

**596**
**596 Pending mod message** 

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) before making any new API calls.

```json
{
  "error": 
    "Your PixVerse account has pending error." 
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    video_id: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/upscale" \
     -d '{"video_id": "…"}'
```

**JavaScript**
``` javascript
const video_id = "video_id";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/upscale`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  video_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
video_id = "video_id"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/upscale" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "video_id": f"{video_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/start-here/setup-runwayml ===
Document URL: https://useapi.net/docs/start-here/setup-runwayml
# <img style="height:1em;vertical-align: middle;" src="/assets/images/runwayml.svg"> Setup Runway
## Table of contents
<small>Approximately 2 minutes to complete setup steps.</small>  

---
> This is the setup guide for [Runway API](/docs/api-runwayml-v1). A [Runway](https://runwayml.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

## Create Runway account

You need a [Runway](https://runwayml.com) account. Create a [new account](https://app.runwayml.com/login) if you don't have one already.

Please note even if you have an existing Runway account we are **strongly** recommending creating a separate Runway account specifically designated to be used with useapi.net API.   

You can start with a free Runway account and upgrade to a paid account once you feel comfortable with the API offerings. 

For free Runway accounts, the following features are unlocked with this experimental API:
* Unlimited number of [Text to Image Preview](/docs/api-runwayml-v1/get-runwayml-text_to_image_preview) generations
* Unlimited number of [Image Upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) generations
* Unlimited number of [Transcribe](/docs/api-runwayml-v1/get-runwayml-transcribe) generations
* Unlimited number of [Super-Slow Motion](/docs/api-runwayml-v1/post-runwayml-super_slow_motion) generations
* Unlimited number of [Frames Describe](/docs/api-runwayml-v1/get-runwayml-frames-describe) generations

When creating a new account, choose the **email option**. The API will not work with accounts created using Sign up with Google, Sign up with Apple, or Use Single Sign-On (SSO) options.

![](/assets/images/runwayml_setup_1.png)

## Configure API

Now that you have a Runway account, configure it for API access using [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful.

=== URL: https://useapi.net/docs/api-runwayml-v1 ===
Document URL: https://useapi.net/docs/api-runwayml-v1

# <img style="height:1em;vertical-align: middle;" src="/assets/images/runwayml.svg"> Runway API v1 
<small>August 8, 2024 (May 15, 2026)</small>

This is [experimental](/docs/legal) API for for the [Runway AI](https://runwayml.com).

Our API supports **all** the functionality for Gen-4.5, Gen-4, Gen-4 Turbo available on the original [Runway AI](https://runwayml.com/) website. This includes [Text](/docs/api-runwayml-v1/post-runwayml-gen4_5-create)/[Image](/docs/api-runwayml-v1/post-runwayml-gen4-create)/[Video](/docs/api-runwayml-v1/post-runwayml-gen4-video)-to-Video, [Act Two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two), [Aleph](/docs/api-runwayml-v1/post-runwayml-gen4-video), [Lip Sync](/docs/api-runwayml-v1/post-runwayml-lipsync-create), [Images](/docs/api-runwayml-v1/post-runwayml-images-create), [Videos](/docs/api-runwayml-v1/post-runwayml-videos-create), [Frames](/docs/api-runwayml-v1/post-runwayml-frames-create) and more. We're fully committed to bringing all the [Runway AI](https://runwayml.com/) website magic to our API customers.

The [Videos](/docs/api-runwayml-v1/post-runwayml-videos-create) is a unified video generation endpoint supporting 18 AI models: [Seedance 2.0](https://seed.bytedance.com/), [HappyHorse 1.0](https://fal.ai/happyhorse-1.0), [Kling O3 4K/Pro/Standard](https://klingai.com) (omni — Frames, Multishot, Edit Video), [Kling 3.0 Pro/Standard](https://klingai.com), [Kling 3.0 Motion Control](https://klingai.com) (character animation via motion transfer), [Kling 2.6 Pro/I2V](https://klingai.com), [Wan 2.6 Flash](https://wan.video/), [Wan 2.2 Animate](https://github.com/Wan-Video/Wan2.2), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2/Pro](https://openai.com/index/sora/), and [Gen-4.5, Gen-4, Gen-4 Turbo](https://runwayml.com) with text-to-video, image-to-video, keyframe, and multi-reference (up to 11 mixed images + videos) workflows. Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can use `exploreMode` to generate videos without using credits — all models except Veo 3.1 support unlimited mode.

The [Videos Upscale](/docs/api-runwayml-v1/post-runwayml-videos-upscale) upscales a video to 4K using Topaz AI (source aspect ratio preserved; max 40s). Unlimited with `exploreMode`.

The [Images](/docs/api-runwayml-v1/post-runwayml-images-create) is a unified image generation endpoint supporting 11 AI models: [FLUX.2 Max](https://bfl.ai), [FLUX.2 Klein](https://bfl.ai), [Nano Banana](https://deepmind.google/models/gemini/flash/), [Nano Banana 2](https://deepmind.google/models/gemini/flash/), [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/), [GPT Image 1.5](https://platform.openai.com/docs/models/gpt-image-1), [GPT Image 1 Mini](https://platform.openai.com/docs/models/gpt-image-1-mini), [GPT Image 2](https://openai.com/), [Seedream 5](https://www.volcengine.com/product/seedream), Gen-4, and Gen-4 Turbo with text-to-image and reference image workflows. Nano Banana, Nano Banana 2, and Nano Banana Pro support image references of famous people and minors, unlike [Google Flow](/docs/api-google-flow-v1). Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can use `exploreMode` to generate images without using credits — all models support unlimited mode.

The [Lip Sync](/docs/api-runwayml-v1/post-runwayml-lipsync-create) enables you to use an image or video to create generative videos where the selected face speaks lines from your audio clips or AI-generated voices (28+ languages, model [eleven_multilingual_v2](https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them)). 

For **free** Runway accounts, the following features are unlocked with this experimental API:
* Unlimited number of [Image Upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) generations
* Unlimited number of [Transcribe](/docs/api-runwayml-v1/get-runwayml-transcribe) generations
* Unlimited number of [Super-Slow Motion](/docs/api-runwayml-v1/post-runwayml-super_slow_motion) generations
* Unlimited number of [Frames Describe](/docs/api-runwayml-v1/get-runwayml-frames-describe) generations

[Setup Runway](/docs/start-here/setup-runwayml)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(May 15, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-runwayml-v1.txt) <small>Feed this to your LLM to build integrations</small>

[Q&A: How is your experimental Runway API different from the official Runway API?](/docs/questions-and-answers#how-is-your-experimental-runway-api-different-from-the-official-runway-api)

Articles:
* [Create Runway videos like a Pro](/docs/articles/runway-bash)
* [Mastering Runway Frames](/docs/articles/runway-frames-script)

Examples:
* [Seedance 2.0 — real-face tutorial (Runway & Dreamina)](/blog/260415)
* [16+ AI Image Models: The Showdown](/blog/260309i)
* [Veo, Kling, Sora, Wan videos and Nano Banana, Seedream images](/blog/260305)
* [Nano Banana Pro images](/blog/260217)
* [Gen-4.5 image-to-video](/blog/260123)
* [Gen-4.5 text-to-video](/blog/251215)
* [Act Two](/blog/250722)
* [Act Two voice swap](/blog/250908)
* [Aleph](/blog/250804)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/runwayml_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/runwayml_api</a>

=== URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-accounts-email ===
Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-accounts-email
## Delete Runway API account
<small>August 8, 2024</small>

---
> **https://api.useapi.net/v1/runwayml/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/runwayml/accounts/<email> 
```

**JavaScript**
``` javascript
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
email = "Previously configured email" 
apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-assets-assetId ===
Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-assets-assetId
## Delete asset 
<small>August 8, 2024</small>

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).
> **https://api.useapi.net/v1/runwayml/assets/`assetId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `assetId` is **required**. Specify assetId you want to delete.

##### Responses 

**200**
**200 OK**  
```json
{
  "success": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Not found."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  success: boolean,
  error: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v1/runwayml/assets/assetId" 
```

**JavaScript**
``` javascript
const assetId = "assetId to delete"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/assets/${assetId}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId to delete" 
apiUrl = f"https://api.useapi.net/v1/runwayml/assets/{assetId}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-scheduler-taskId ===
Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-scheduler-taskId
## Cancel task currently being executed by the API
<small>August 8, 2024</small>

---
> **https://api.useapi.net/v1/runwayml/scheduler/`taskId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `taskId` is **required**. Specify taskId you want to cancel.

##### Responses 

**204**
**204 No Content**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Unable to locate running taskId <taskId>"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v1/runwayml/scheduler/taskId" 
```

**JavaScript**
``` javascript
const taskId = "taskId to cancel"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/scheduler/${taskId}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
taskId = "taskId to cancel" 
apiUrl = f"https://api.useapi.net/v1/runwayml/scheduler/{taskId}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-tasks-taskId ===
Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-tasks-taskId
## Delete task 
<small>August 8, 2024</small>

---
> **https://api.useapi.net/v1/runwayml/tasks/`taskId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `taskId` is **required**. Specify taskId you want to delete.

##### Responses 

**200**
**200 OK**  
```json
{
  "success": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Not found."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  success: boolean,
  error: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v1/runwayml/tasks/taskId" 
```

**JavaScript**
``` javascript
const taskId = "taskId to delete"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/${taskId}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
taskId = "taskId to delete" 
apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/{taskId}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts-email ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts-email
## Retrieve Runway API account configuration for `email` 
<small>August 8, 2024</small>

---
> **https://api.useapi.net/v1/runwayml/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**201**
**201 Created**
```json
{
  "email": "user-1@example.com",
  "password": "<password>",
  "maxJobs": 5,
  "jwt": {
    "token": "<token>",
    "exp": 1734858598.864,
    "iat": 1732266598.864,
    "id": 123456,
  }        
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string,
  password: string,
  maxJobs: number,
  jwt: {
    token: string,
    exp: number,
    iat: number,
    id: number,
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/runwayml/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured email"
apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts
## Retrieve Runway API accounts configuration
<small>August 8, 2024</small>

---

For your convenience, you can specify your Runway configuration values under your Runway account. If you specify multiple Runway accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Runway.

This endpoint retrieves the complete list of configured API accounts for Runway.
> **https://api.useapi.net/v1/runwayml/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "user-1@example.com": {
        "email": "user-1@example.com",
        "password": "<password>"
        "jwt": {
            "token": "<token>",
            "exp": 1734858598.864,
            "iat": 1732266598.864,
            "id": 123456,
        },
        "maxJobs": 5,
    },
    "user-N@example.com": {
        "email": "user-N@example.com",
        "password": "<password>"
        "jwt": {
            "token": "<token>",
            "exp": 1744858598.864,
            "iat": 1742266598.864,
            "id": 78910,
        },
        "maxJobs": 5,
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [email: string]: {
    email: string,
    password: string,
    maxJobs: number,
    jwt: {
      token: string,
      exp: number,
      iat: number,
      id: number,
    }
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/runwayml/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/runwayml/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/runwayml/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets-assetId ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets-assetId
## Retrieve assets 
<small>August 8, 2024</small>

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).
> **https://api.useapi.net/v1/runwayml/assets/`assetId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `assetId` is **required**. Specify the assetId you want to retrieve. 

##### Responses 

**200**
**200 OK**  

```json
{
    "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid",
    "id": "<asset uuid>",
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "name": "Race car.jpg",
    "url": "<asset url>",
    "previewUrls": ["<asset preview url>"],
    "mediaType": "image",
    "fileCount": 1,
    "fileSize": 123456,
    "fileExtStandardized": "jpeg",
    "isUserUpload": true,
    "metadata": null,
    "username": "<user name>",
    "userId": 123456789,
    "createdBy": 123456789,
    "userPicture": null,
    "private": true,
    "privateInTeam": true,
    "parentAssetGroupId": null,
    "favorite": false
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    assetId: string,
    id: string,
    createdAt: string,
    updatedAt: string,
    name: string,
    url: string,
    previewUrls: string[],
    mediaType: string,
    mediaSubtype: string,
    fileCount: number,
    fileSize: number,
    fileExtStandardized: string,
    isUserUpload: boolean,
    metadata: {
      frameRate: number,
      duration: number,
      dimensions: number[],
      size: {
          width: number,
          height: number
      }
    },
    username: string,
    userPicture: string,
    userId: number,
    createdBy: number,
    private: boolean,
    privateInTeam: boolean,
    parentAssetGroupId: string,
    taskId: string,
    favorite: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/assets/assetId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const assetId = "assetId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/assets/${assetId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
assetId = "assetId to retrieve"
apiUrl = f"https://api.useapi.net/v1/runwayml/assets/{assetId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets
## Retrieve assets 
<small>August 8, 2024 (August 4, 2025)</small>

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).
> **https://api.useapi.net/v1/runwayml/assets/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  
- `offset` is **required**. This parameter is used to facilitate pagination.  
  Valid range 0…1000.  
- `limit` is **required**. This parameter is used to facilitate pagination.  
  Valid range 1…50.  
- `mediaType` is optional. Specify which asset media types you want to retrieve.   
  Supported values: `video`, `image` and `audio`.  

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid",
        "id": "<asset uuid>",
        "createdAt": "2024-08-01T01:02:03.456Z",
        "updatedAt": "2024-08-01T01:02:03.456Z",
        "name": "Gen-3 Alpha 35801490234, funny cats jumping over.mp4",
        "url": "<assets url>",
        "previewUrls": ["<asset preview url>"],
        "mediaType": "video",
        "mediaSubtype": null,
        "fileCount": 1,
        "fileSize": 1234567,
        "fileExtStandardized": "mp4",
        "isUserUpload": false,
        "metadata": {
            "frameRate": 24,
            "duration": 10.542,
            "width": 1280,
            "height": 768,
            "hasAlphaChannel": false,
            "hasAudio": true
        },
        "username": "<user name>",
        "userPicture": null,
        "userId": 123456789,
        "createdBy": 123456789,
        "private": true,
        "privateInTeam": true,
        "parentAssetGroupId": "<uuid>",
        "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
        "favorite": false,
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    assetId: string,
    id: string,
    createdAt: string,
    updatedAt: string,
    name: string,
    url: string,
    previewUrls: string[],
    mediaType: string,
    mediaSubtype: string,
    fileCount: number,
    fileSize: number,
    fileExtStandardized: string,
    isUserUpload: boolean,
    metadata: {
      frameRate: number,
      duration: number,
      width: number,
      height: number,
      hasAlphaChannel: boolean,
      hasAudio: boolean
    },
    username: string,
    userPicture: string,
    userId: number,
    createdBy: number,
    private: boolean,
    privateInTeam: boolean,
    parentAssetGroupId: string,
    taskId: string,
    favorite: boolean
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured email"
apiUrl = f"https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features
## Retrieve the Runway account features
<small>August 8, 2024</small>

---

Retrieve account credits information and other details.
> **https://api.useapi.net/v1/runwayml/features/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes required.
  
##### Responses 

**200**
**200 OK**  

The response below has been omitted for brevity to include only essential fields, the live endpoint will return a much larger response.

```json
{
    "permitted": {
        "storageGB": 500,
        "numPlanCredits": 2250
    },
    "used": {
        "numPlanCredits": 1315
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

The model below has been omitted for brevity to include only essential fields, the live endpoint will return many more fields.

```typescript
{ // TypeScript, all fields are optional
  permitted: {
      storageGB: number,
      numPlanCredits: number
  },
  used: {
      numPlanCredits: number
  }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/features/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/features/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured email"
apiUrl = f"https://api.useapi.net/v1/runwayml/features/?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-frames-describe ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-frames-describe
## Get image description 
<small>February 24, 2025 (April 28, 2025)</small>

---

Extract a text image description that can be adjusted and used as a starting point for the prompt in [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create).

This endpoint is available for all Runway accounts, including free ones.
> **https://api.useapi.net/v1/runwayml/frames/describe/`image_assetId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `image_assetId` is **required**. Specify the image asset. You can upload an image via [POST assets](/docs/api-runwayml-v1/post-runwayml-assets), you can get a list of all image assets via [GET assets](/docs/api-runwayml-v1/get-runwayml-assets).

##### Responses 

**200**
**200 OK**  

```json
{
    "textPrompt": "Subject: A woman wearing an elegant Greco-Roman style ivory silk dress with ornate golden embellishments at the neckline and waist. Multiple golden bangles adorn her wrists as she stands in a graceful pose with one hand extended to touch a column.\n\nScene: Ancient stone columns with weathered surfaces frame a shadowy interior space. The architectural elements suggest a classical temple or palace setting with fluted pillars and worn stone textures visible in the warm lighting.\n\nStyle: Dramatic chiaroscuro lighting creates deep shadows while highlighting the luxurious fabric draping and metallic details. The composition emphasizes classical beauty through careful attention to form, texture, and light interplay. Professional fashion photography meets fine art painting aesthetic. Classical, dramatic lighting, textile-focused, painterly, architectural."
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    textPrompt: string
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/frames/describe/image_assetId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const image_assetId = "image_assetId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/frames/describe/${image_assetId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
image_assetId = "image_assetId to retrieve"
apiUrl = f"https://api.useapi.net/v1/runwayml/frames/describe/{image_assetId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-image_upscaler ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-image_upscaler
## Upscale or Downscale image to specified dimensions
<small>August 8, 2024</small>

---

Runway [AI Tools » Audio tools » Upscale Image](https://app.runwayml.com/video-tools/ai-tools/upscale-image).  

This endpoint provides **free** & **unlimited** image upscaling/downscaling services. It works with **free** accounts without any limitations as well. 
> **https://api.useapi.net/v1/runwayml/image_upscaler/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  
- `image_url` is **required**. Image URL should be either the URL provided by [text_to_image_preview](/docs/api-runwayml-v1/get-runwayml-text_to_image_preview) or an asset URL from [GET /assets](/docs/api-runwayml-v1/get-runwayml-assets). You may need to upload the image using [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) and use the URL provided for this parameter.
- `weight`  is **required**. Specify image width.
- `height` is **required**. Specify image height.

##### Responses 

**200**
**200 OK**  

Binary response containing a new image.

**400**
**400 Bad Request**
```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
    "message": "Image was not found"
}
```

##### Model 
```typescript
Binary stream in case of HTTP 200 response. 

Otherwise see type provided below:
{ // TypeScript, all fields are optional
    error: string,
    message: string,
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/image_upscaler/?image_url=https://…image.jpg&width=100&height=100" \
   -H "Accept: application/json" \
   -o resized_image.jpg
```

**JavaScript**
``` javascript
const token = "API token";
const image_url="https://…image.jpg";
const width = 100;
const height = 200;
const apiUrl = `https://api.useapi.net/v1/runwayml/image_upscaler/?image_url=${image_url}&width=${width}&height=${height}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
console.log("response", {response, result});
// response.blob() contains resized image
// • Node.js saving resized image to file:
// response.blob()
//     .then(blob => blob.arrayBuffer())
//     .then(buffer => fs.writeFile('resized_image.jpg', Buffer.from(buffer)));
// • Displaying response as an image on the webpage, as you see below in Try It section:
// const imageBlob = await response.blob();
// const imageUrl = URL.createObjectURL(imageBlob);
// const imageElement = document.getElementById('your-image-id');
// imageElement.src = imageUrl;
```

**Python**
``` python
import requests
# from io import BytesIO
# from PIL import Image

token = "API token"
image_url = "https://…image.jpg"
width = 100
height = 200
api_url = f"https://api.useapi.net/v1/runwayml/image_upscaler/?image_url={image_url}&width={width}&height={height}"

headers = {
    "Authorization": f"Bearer {token}",
}

response = requests.get(api_url, headers=headers)

with open('resized_image.jpg', 'wb') as f:
  f.write(response.content)
    
# • Display the image (for example in a Jupyter Notebook)
# image_stream = BytesIO(response.content)
# image = Image.open(image_stream)
# image.show()
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-lipsync-voices ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-lipsync-voices
## Retrieve the list of available AI voices 
<small>August 8, 2024</small>

---

Runway [AI Tools » Audio tools » Generative Audio](https://app.runwayml.com/video-tools/ai-tools/generative-audio).  
Runway [AI Tools » Audio tools » Lip Sync Video](https://app.runwayml.com/video-tools/ai-tools/generative-audio).  
> **https://api.useapi.net/v1/runwayml/lipsync/voices/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes 
  
##### Responses 

**200**
**200 OK**  
```json
[
    {
        "voiceId": "pNInz6obpgDQGcFmaJgB",
        "createdAt": "2024-08-01T01:02:03.456Z",
        "updatedAt": "2024-08-01T01:02:03.456Z",
        "name": "Benjamin",
        "description": "",
        "labels": {
            "accent": "american",
            "description": "deep",
            "age": "middle aged",
            "gender": "male",
            "use case": "narration"
        },
        "privateInTeam": true,
        "createdBy": 1234567,
        "sample": "https://runwayml.cloudfront.net/app/magic-tools/text-to-speech-voice-samples/Benjamin.mp3"
    },
    {
        "voiceId": "XB0fDUnXU5powFXDhCwa",
        "createdAt": "2024-08-01T01:02:03.456Z",
        "updatedAt": "2024-08-01T01:02:03.456Z",
        "name": "Claudia",
        "description": "",
        "labels": {
            "accent": "british-swedish",
            "description": "seductive",
            "age": "young",
            "gender": "female",
            "use case": "characters"
        },
        "privateInTeam": true,
        "createdBy": 1234567,
        "sample": "https://runwayml.cloudfront.net/app/magic-tools/text-to-speech-voice-samples/Claudia.mp3"
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  voiceId: string,
  createdAt: string,
  lastUsedAt: string,
  name: string,
  description: string,
  labels: {
    accent: string,
    age: string,
    gender: string,
    use_case: string,
    description: string,
    descriptive: string,
    language: string,
    usecase: string,
  }
  privateInTeam: boolean,
  createdBy: number,
  sample: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/lipsync/voices/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/lipsync/voices/?email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured email"
apiUrl = f"https://api.useapi.net/v1/runwayml/lipsync/voices/?email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler
## Retrieve the list of tasks currently being executed by the API
<small>August 8, 2024</small>

---

This endpoint retrieves the list of tasks currently being executed by the API. If you want to get all tasks currently being executed including you manually initiated from Runway website use [GET /tasks](/docs/api-runwayml-v1/get-runwayml-tasks).    
Example <small>[…/tasks/?statuses=PENDING,RUNNING,THROTTLED&offset=0&limit=50](/docs/api-runwayml-v1/get-runwayml-tasks)</small>.
> **https://api.useapi.net/v1/runwayml/scheduler/**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
[
    {
        "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    taskId: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/runwayml/scheduler/`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/runwayml/scheduler/"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks-taskId ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks-taskId
## Retrieve task 
<small>August 8, 2024 (December 15, 2025)</small>

---

Use this endpoint to retrieve status and results of

* [gen4_5/create](/docs/api-runwayml-v1/post-runwayml-gen4_5-create)
* [gen4turbo/create](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create)
* [gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create)
* [gen4/upscale](/docs/api-runwayml-v1/post-runwayml-gen4-upscale)
* [gen4/act-two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two)
* [gen4/act-two-voice](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) 
* [gen4/video](/docs/api-runwayml-v1/post-runwayml-gen4-video)
* [gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](/docs/api-runwayml-v1/post-runwayml-gen3-actone)
* [gen3alpha/upscale](/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale)
* [lipsync/create](/docs/api-runwayml-v1/post-runwayml-lipsync-create)
* [frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create)
> **https://api.useapi.net/v1/runwayml/tasks/`taskId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `taskId` is **required**. Specify the taskId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid"
    "id": "<task uuid>",
    "name": "Gen-3 Alpha 123456, Slow motion zoom in, cat chasing dog in the kitchen",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen3a",
    "options": {
      "name": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen",
      "seconds": 5,
      "text_prompt": "Slow motion zoom in",
      "seed": 123456789,
      "exploreMode": true,
      "watermark": false,
      "enhance_prompt": false,
      "init_image": "<asset image url>",
      "resolution": "720p",
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
    },
    "status": "SUCCEEDED",
    "error": null,
    "progressText": null,
    "progressRatio": "1",
    "estimatedTimeToStartSeconds": null,
    "artifacts": [
      {
        "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid",
        "id": "<asset uuid>",
        "createdAt": "2024-08-01T01:02:03.456Z",
        "updatedAt": "2024-08-01T01:02:03.456Z",
        "userId": 1234567,
        "createdBy": 1234567,
        "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
        "parentAssetGroupId": "<group uuid>",
        "filename": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen",
        "url": "<asset url>",
        "fileSize": "12345678",
        "isDirectory": false,
        "previewUrls": ["<asset preview url>"],
        "private": true,
        "privateInTeam": true,
        "deleted": false,
        "reported": false,
        "metadata": {
          "frameRate": 24,
          "duration": 5.209,
          "dimensions": [
            1280,
            768
          ],
          "size": {
            "width": 1280,
            "height": 768
          }
        },
        "favorite": false        
      }
    ],
    "sharedAsset": null    
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
    name: string,
    seconds: number,
    gen2Options: {
      mode: string,
      text_prompt: string,
      seed: number,
      interpolate: boolean,
      upscale: boolean,
      watermark: boolean,
      motion_score: number,
      use_motion_score: boolean,
      use_motion_vectors: boolean,
      style: string,
      width: number,
      height: number,
      motion_vector: {
        x: number,
        y: number,
        r: number,
        z: number,
        bg_x_pan: number,
        bg_y_pan: number
      },
      init_video: string,
      image_prompt: string,
      init_image: string,
      keyframes: { image: string, timestamp: number }[],
      extended_from_task_id: string
    },
    gen_audio_options: {
      name: string,
      text: string,
      voice_id: string,
      model_id: string
    },
    paid_user_watermark_override: boolean,
    recordingEnabled: boolean,
    exploreMode: boolean,
    assetGroupName: string,
    image: string,
    video: string,
    image_asset_id: string,
    video_asset_id: string,
    audio: string,
    audio_asset_id: string,
    watermark: boolean,
    text_prompt: string,
    seed: number,
    image_as_end_frame: boolean,
    init_video: string,
    extended_from_task_id: string,
    video_prompt: string,
    flip: boolean,
    width: number,
    height: number,    
    structure_transformation: number
  },
  status: string,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  progressText: string,
  progressRatio: string,
  estimatedTimeToStartSeconds: number,
  assetId: string,
  sharedAsset: any,
  artifacts: {
    taskId: string,
    id: string,
    createdAt: string,
    updatedAt: string,
    userId: number,
    createdBy: number,
    parentAssetGroupId: string,
    filename: string,
    url: string,
    fileSize: string,
    isDirectory: boolean,
    previewUrls: string[],
    private: boolean,
    privateInTeam: boolean,
    deleted: boolean,
    reported: boolean,
    metadata: {
      frameRate: number,
      duration: number,
      dimensions: [number, number],
      size: {
        width: number,
        height: number
      }
    },
    favorite: boolean,
  }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/tasks/taskId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const taskId = "taskId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/${taskId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
taskId = "taskId to retrieve"
apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/{taskId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks
## Retrieve tasks 
<small>August 8, 2024</small>

---
> **https://api.useapi.net/v1/runwayml/tasks/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  
- `offset` is **required**. This parameter is used to facilitate pagination.   
  Valid range 0…1000.  
- `limit` is **required** . This parameter is used to facilitate pagination.  
  Valid range 1…1000.  
- `statuses` is optional. Filter results by a comma-separated list of task statuses, e.g. `PENDING,RUNNING,THROTTLED`.   
  Supported values: `PENDING`, `RUNNING`, `THROTTLED`, `SUCCEEDED` and `FAILED`.  

##### Responses 

**200**
**200 OK**  
Retrieving `taskId` <small>[…/tasks/?taskId=task_id](https://api.useapi.net/v1/runwayml/tasks/?taskId=task_id)</small>
```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid"
    "id": "<task uuid>",
    "name": "Gen-3 Alpha 123456, Slow motion zoom in, cat chasing dog in the kitchen",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen3a",
    "options": {
      "name": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen",
      "seconds": 5,
      "text_prompt": "Slow motion zoom in",
      "seed": 123456789,
      "exploreMode": true,
      "watermark": false,
      "enhance_prompt": false,
      "init_image": "<asset image url>",
      "resolution": "720p",
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
    },
    "status": "SUCCEEDED",
    "error": null,
    "progressText": null,
    "progressRatio": "1",
    "estimatedTimeToStartSeconds": null,
    "artifacts": [
      {
        "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid",
        "id": "<asset uuid>",
        "createdAt": "2024-08-01T01:02:03.456Z",
        "updatedAt": "2024-08-01T01:02:03.456Z",
        "userId": 1234567,
        "createdBy": 1234567,
        "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
        "parentAssetGroupId": "<group uuid>",
        "filename": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen",
        "url": "<asset url>",
        "fileSize": "12345678",
        "isDirectory": false,
        "previewUrls": ["<asset preview url>"],
        "private": true,
        "privateInTeam": true,
        "deleted": false,
        "reported": false,
        "metadata": {
          "frameRate": 24,
          "duration": 5.209,
          "dimensions": [
            1280,
            768
          ],
          "size": {
            "width": 1280,
            "height": 768
          }
        },
        "favorite": false        
      }
    ],
    "sharedAsset": null    
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
    name: string,
    seconds: number,
    gen2Options: {
      mode: string,
      text_prompt: string,
      seed: number,
      interpolate: boolean,
      upscale: boolean,
      watermark: boolean,
      motion_score: number,
      use_motion_score: boolean,
      use_motion_vectors: boolean,
      style: string,
      width: number,
      height: number,
      motion_vector: {
        x: number,
        y: number,
        r: number,
        z: number,
        bg_x_pan: number,
        bg_y_pan: number
      },
      init_video: string,
      image_prompt: string,
      init_image: string,
      extended_from_task_id: string
    },
    gen_audio_options: {
      name: string,
      text: string,
      voice_id: string,
      model_id: string
    },
    paid_user_watermark_override: boolean,
    recordingEnabled: boolean,
    exploreMode: boolean,
    assetGroupName: string,
    image: string,
    video: string,
    image_asset_id: string,
    video_asset_id: string,
    audio: string,
    audio_asset_id: string
    watermark: boolean,
    text_prompt: string,
    seed: number,
    image_as_end_frame: boolean,
    init_video: string,
    extended_from_task_id: string
  },
  status: string,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  progressText: string,
  progressRatio: string,
  estimatedTimeToStartSeconds: number,
  assetId: string,
  sharedAsset: any,
  artifacts: {
    taskId: string,
    id: string,
    createdAt: string,
    updatedAt: string,
    userId: number,
    createdBy: number,
    parentAssetGroupId: string,
    filename: string,
    url: string,
    fileSize: string,
    isDirectory: boolean,
    previewUrls: string[],
    private: boolean,
    privateInTeam: boolean,
    deleted: boolean,
    reported: boolean,
    metadata: {
      frameRate: number,
      duration: number,
      dimensions: [number, number],
      size: {
        width: number,
        height: number
      }
    },
    favorite: boolean,
  }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const email = "Previously configured email"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email=${email}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
email = "Previously configured email"
apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email={email}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-text_to_image_preview ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-text_to_image_preview
## Text to Image instant generation (Stable Diffusion) <span class="required-input-field"><b>(retired)</b></span> 
<small>August 8, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-2. This endpoint no loner available.</b></span>

---

<span class="required-input-field"><b>Important</b></span>  
**Runway retired this endpoint in September 2025.  
Please use [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create) instead.**

Runway [AI Tools » Video tools » Gen-2 Text/Image to Video](https://app.runwayml.com/video-tools/ai-tools/generative-video) page, <input disabled type="button" value="Free preview" style="color: currentColor;"> button.

This endpoint provides **free** & **unlimited** Stable Diffusion text-to-image generations. It works with **free** accounts without any limitations as well. It takes on average between 10 to 60 seconds to complete. You can make multiple requests in parallel.  

Please be aware that Runway's moderation system analyzes your prompt and may respond with `403` if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated prompts, which may result in your account being suspended when the internal threshold is exceeded.  
> **https://api.useapi.net/v1/runwayml/text_to_image_preview/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  
- `text_prompt` is **required**. Specify text prompt.
- `prompt_weight` is optional. Specify weight of the prompt.  
  Valid range 1...30.
- `negative_prompt` is optional. Specify negative prompt.  
- `seed` is optional.   
  Valid range 1…4294967294.  
- `style` is optional. If not provided `cinematic` will be used by default.  
  Supported values: `cinematic`, `abandoned`, `abstract_sculpture`, `advertising`, `anime`, `architectural`, `cartoon`, `cine_lens`, `claymation`, `concept_art`, `digital_art`, `duotone_artistic_photo`, `forestpunk`, `frost`, `graphic_novel`, `graphite`, `impressionist_painting`, `isometric_3d`, `low_poly_3d`, `macro_photography`, `marker_drawing`, `moody_film`, `pixel_art`, `retro_photography`, `sci-fi_art`, `stickers`, `storyboard`, `actor_casting`, `thriller`, `35mm`, `3d_cartoon`, `3d_render`, `80s_vaporwave`.
- `aspect_ratio` is optional. If not provided `16:9` will be used by default.  
  Supported values: `21:9`,`1:1`, `9:16`, `16:9`, `4:3`, `3:4`

##### Responses 

**200**
**200 OK**  
```json
{
    "url": "<image url>",
    "seed": 1234567
}
```

**400**
**400 Bad Request**
```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**403**
**403 Forbidden**  
Runway moderation message. Runway monitors the rate and the number of moderated prompts, which may result in your account being suspended when the internal threshold is exceeded.
```json
{
  "message": "Text did not pass content moderation.",
  "moderation_category": "SEXUALLY_EXPLICIT",
  "reason": "SAFETY.INPUT.TEXT",
  "tally_asimov": true
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    url: string,
    seed: number,
    error: string,
    message: string,
    moderation_category: string,
    reason: string,
    tally_asimov: boolean,
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/text_to_image_preview/?text_prompt=happy cat" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const text_prompt="happy cat";
const apiUrl = `https://api.useapi.net/v1/runwayml/text_to_image_preview/?text_prompt=${text_prompt}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
text_prompt = "happy cat"
apiUrl = f"https://api.useapi.net/v1/runwayml/text_to_image_preview/?text_prompt={text_prompt}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-transcribe ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-transcribe
## Transcribe audio or video to text
<small>August 8, 2024</small>

---

Runway [AI Tools » Audio tools » Transcript](https://app.runwayml.com/video-tools/ai-tools/subtitles).  

This endpoint provides **free** and **unlimited** audio/video to text transcription services. It works with **free** accounts without any limitations as well. 
> **https://api.useapi.net/v1/runwayml/transcribe/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters
- `assetId` is **required**. Specify the audio or video assetId you want to transcribe. Use [GET /assets](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of assets. To upload a new audio/video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).
- `language`  is **required**. Specify value from table below:  

| Value | Title                    |
| ----- | ------------------------ |
| en    | English                  |
| en_au | English (Australian)     |
| en_uk | English (United Kingdom) |
| en_us | English (United States)  |
| es    | Spanish                  |
| fr    | French                   |
| de    | German                   |
| it    | Italian                  |
| pt    | Portuguese               |
| nl    | Dutch                    |

##### Responses 

**200**
**200 OK**  
```json
{
  "id": "<uuid>",
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "userId": 123455,
  "mediaUrl": "<media url>",
  "languageCode": "en",
  "words": [
    {
      "start": 1400,
      "end": 1560,
      "text": "Hi",
      "confidence": 1,
      "speaker": null
    },
    {
      "start": 1560,
      "end": 1872,
      "text": "there",
      "confidence": 0.89742,
      "speaker": null
    }
  ],
  "status": "completed",
  "utterances": null
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  id: string,
  createdAt: string,
  updatedAt: string,
  userId: number,
  mediaUrl: string,
  languageCode: string,
  words: {
    start: number,
    end: number,
    text: string,
    confidence: number,
    speaker: string
  }[],
  status: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/runwayml/transcribe/?assetId=user:user_id-runwayml:account_email-asset:asset_uuid&language=en" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const assetId = "audio or video assetId"; 
const language = "en";
const apiUrl = `https://api.useapi.net/v1/runwayml/transcribe/?assetId=${assetId}&language=${language}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
assetId = "audio or video assetId"
language = "en"
apiUrl = f"https://api.useapi.net/v1/runwayml/transcribe/?assetId={assetId}&language={language}"; 
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email
## Create or update Runway API account configuration
<small>August 8, 2024</small>

---

For your convenience, you can specify your Runway configuration values under your account. If you specify multiple Runway accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Runway.
> **https://api.useapi.net/v1/runwayml/accounts/`email`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Runway account email",
    "password": "Runway account password",
    "maxJobs": 1-10,
}
```
- `email`, `password` are **required**. Please see [Setup Runway](/docs/start-here/setup-runwayml) for details. 

- `email` value specified in the request body **must match** the email value specified in the URL path <small>https://api.useapi.net/v1/runwayml/accounts/`email`</small>.

- `maxJobs` is **required**. Currently, it should be between 1 and 10. We recommend setting this value to 5.

##### Responses 

**200**
**200 OK** 

```json
{
  "email": "user-1@example.com",
  "password": "<password>",
  "maxJobs": 5,
  "jwt": {
    "token": "<token>",
    "exp": 1734858598.864,
    "iat": 1732266598.864,
    "id": 123456,
  }        
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string,
  password: string,
  maxJobs: number,
  jwt: {
    token: string,
    exp: number,
    iat: number,
    id: number,
  }
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/runwayml/accounts/<email> \
     -d '{"email": "…", "password": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const email = "Runway account email";      
const password = "Runway account password";      
const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${email}`; 
const token = "API token";
const maxJobs = 5;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  email, password, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
email = "Runway account email"
password = "Runway account password"
apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}" 
token = "API token"
maxJobs = 5
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "email": f"{email}",
    "password": f"{password}", 
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets
## Upload the asset to your Runway account
<small>August 8, 2024 (July 22, 2025)</small>

---

Runway [Assets](https://app.runwayml.com/video-tools/assets). 

**IMPORTANT**  
If you have multiple accounts configured, you must specify the desired account where assets will be uploaded via the `email` parameter. All API endpoints where an asset is used will use the same account to execute the generation as the one where the asset was uploaded. So, by uploading an asset to the desired account, you effectively select that account for generation with that asset.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/runwayml/assets/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type        | File Extension |
| ------------------- | -------------- |
| image/png           | png            |
| image/jpeg          | jpeg           |
| image/gif           | gif            |
| image/webp          | webp           |
| image/mpo           | mpo            |
| video/mp4           | mp4            |
| video/quicktime     | mov            |
| video/3gpp          | 3gp            |
| video/x-matroska    | mkv            |
| video/x-flv         | flv            |
| video/mpeg          | mpeg           |
| video/MP2T          | ts             |
| video/x-msvideo     | avi            |
| video/x-motion-jpeg | mjpeg          |
| video/webm          | webm           |
| video/ogg           | ogv            |
| audio/wav           | wav            |
| audio/wave          | wav            |
| audio/mpeg          | mp3            |
| audio/flac          | flac           |
| audio/ogg           | ogg            |
| audio/webm          | webm           |

##### Query Parameters

- `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `name` is **required**. Specify the name of the asset.

- `width` is optional. Specify image or video width in pixels.  
  This value is currently used by the following API endpoints:
  * [super_slow_motion](/docs/api-runwayml-v1/post-runwayml-super_slow_motion).
  
- `height` is optional. Specify image or video height in pixels.   
  This value is currently used by the following API endpoints:
  * [super_slow_motion](/docs/api-runwayml-v1/post-runwayml-super_slow_motion).

##### Request Body

Provide content of the uploaded file as a binary data.

##### Responses 

**200**
**200 OK**  
```json
{
  "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid",
  "id": "<asset uuid>",
  "user": {
    "id": 1234567,
    "username": "<user name>",
    "firstName": "<first name>",
    "lastName": "<last name>",
    "picture": null,
    "teamName": "<team name>",
    "teamPicture": null
  },
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "name": "<asset name>",
  "description": "",
  "type": {
    "name": "image",
    "type": "image",
    "isDirectory": false
  },
  "size": 123456789,
  "url": "<asset url>",
  "previewUrls": ["<asset preview url>"],
  "fileCount": 1,
  "private": true,
  "permissions": {
    "read": true,
    "write": true,
    "admin": true
  },
  "annotated": false,
  "isUserUpload": true,
  "sourceApplication": "web",
  "createdBy": {
    "id": 1234567,
    "username": "<user name>",
    "firstName": "<first name>",
    "lastName": "<last name>",
    "picture": null,
    "teamName": "<team name>",
    "teamPicture": null
  },
  "favorite": false
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  assetId: string,
  id: string,
  user: {
    id: number,
    username: string,
    firstName: string,
    lastName: string,
    picture: string,
    teamName: string,
    teamPicture: string,
  },
  createdAt: string,
  updatedAt: string,
  name: string,
  description: string,
  type: {
    name: string,
    type: string,
    isDirectory: boolean,
  },
  size: number,
  url: string,
  previewUrls: string[],
  fileCount: number,
  private: boolean,
  permissions: {
    read: boolean,
    write: boolean,
    admin: boolean,
  },
  annotated: boolean,
  isUserUpload: boolean,
  sourceApplication: string,
  createdBy: {
    id: number,
    username: string,
    firstName: string,
    lastName: string,
    picture: string,
    teamName: string,
    teamPicture: string,
  },
  favorite: boolean  
}
```

##### Examples

**Curl**
``` bash
curl -X POST "https://api.useapi.net/v1/runwayml/assets/?name=your_file_name" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: image/jpeg" \
  --data-binary /path/to/your/image_or_video_or_audio_file.jpeg
```

**JavaScript**
``` javascript
const token = "API token";
const name = "asset name"; 
const apiUrl = `https://api.useapi.net/v1/runwayml/assets/?name=${name}`; 
let blob;
/*
    // Example 1: Fetch image from URL
    const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
    const responseImage = await fetch(imageUrl);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load image from local file (Blob)
    const fsp = require('fs').promises;
    const imageFileName = "./cat.png";
    blob = new Blob([await fsp.readFile(imageFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="image-file" type="file"> 
    const imageFile = document.getElementById(`image-file`);
    if (imageFile.files[0])
        blob = imageFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests

token = "API token"
name = "asset name"
email = "email"
api_url = f"https://api.useapi.net/v1/runwayml/assets/?name={name}&email={email}"

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# file_content = response_image.content

# # Example 2: Load image from local file
# image_file_path = "./image.jpg"
# with open(image_file_path, 'rb') as image_file:
#     file_content = image_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create
## Frames
<small>January 29, 2025 (June 6, 2025)</small>

---

Frames is Runway's most advanced base model for image generation, offering unprecedented stylistic control and visual fidelity.

This endpoint will generate 4 high-definition 1080p images in under 20 seconds on average. You can also run several generations in parallel.

[Frames Prompting Guide](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide).

[References Guide](https://help.runwayml.com/hc/en-us/articles/40042718905875-References-Guide).

You can specify the first, second, and third reference images via the `imageAssetId1`, `imageAssetId2`, and `imageAssetId3` parameters and refer to them in the prompt as `@IMG_1`, `@IMG_2`, and `@IMG_3`. See [example](/blog/250430).

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

See article [Mastering Runway Frames](/docs/articles/runway-frames-script) featuring a script for batch-generating images using Runway Frames.

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/frames/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional Runway API account email",
    "text_prompt": "Required text prompt",
    "aspect_ratio": "21:9",
    "diversity": 5,
    "num_images": 4,
    "style": "vivid",
    "seed": 12345678,
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```
- `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts).  

- `text_prompt` is **required**. Describe your image in detail. [Frames Prompting Guide](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide).   
  Maximum length 1000 characters.  

- `imageAssetId1`, `imageAssetId2` and `imageAssetId3` are optional. Specify the assetIds of the first, second and third reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Parameters can be referred in the prompt as `@IMG_1`, `@IMG_2`, and `@IMG_3`. See [example](/blog/250430).
 

- `style` is optional.   
  Supported values: `vivid`, `vivid-warm`, `vivid-cool`, `high-contrast`, `high-contrast-warm`, `high-contrast-cool`, `bw`, `bw-contrast`, `muted-pastel`, `dreamscape`, `nordic-minimal`, `light-anime`, `dark-anime`, `painted-anime`, `3d-cartoon`, `sketch`, `low-angle`, `in-motion`, `terracotta`.

- `aspect_ratio` is optional.   
  Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.

- `diversity` is optional. Aesthetic Range, higher values increase the creative variation between generations in a set.   
  Valid range: 0…5. Default 2.  

- `num_images` is optional.   
  Supported values: `1` (default), `4`.
  
- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.   
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated images can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-frames-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "text_to_image",
    "options": {
        "name": "<name>",
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "diversity": 2,
        "num_images": 4,
        "style": "vivid",
        "width": 1088,
        "height": 1920,
        "flip": true,
        "assetGroupName": "Text to Image",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [frames/create](#frames) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
        name: string,
        text_prompt: string,
        diversity: number,
        style: string,
        seed: number,
        exploreMode: boolean,
        flip: boolean,
        width: number,
        height: number,
        num_images: number,
        assetGroupName: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },  
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/frames/create" \
     -d '{"text_prompt": "…"}'
```

**JavaScript**
``` javascript
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/frames/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/frames/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen2-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen2-create
## Create a 4-second-long video using text and/or image prompts
<small>August 8, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-2. This endpoint no loner available.</b></span>

---

Runway [AI Tools » Audio tools » Text/Image to Video » Gen-2](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen2/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional Runway API account email",
    "text_prompt": "Optional text prompt",
    "image_assetId": "Optional assetId of image asset",
    "image_preview": "Optional image URL generated by GET /text_to_image_preview",
    "upscale": true,
    "interpolate": true,
    "style": "pixel_art",
    "aspect_ratio": "3:4",
    "motion": 10,
    "horizontal": -10,
    "vertical": -5,
    "roll": -1,
    "zoom": 2,
    "pan": 5,
    "tilt": 10,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `email` is optional, if not provided and parameter `image_assetId` is not specified API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts).  

- `text_prompt` is optional. Describe your shot. [Gen-2 prompt tips](https://help.runwayml.com/hc/en-us/articles/17329337959699-Gen-2-prompt-tips).

- `image_assetId` is optional. Specify the image assetId you want to be present in the first frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).   
  Specify `image_assetId` or `image_preview` but not both.

- `image_preview` is optional. Specify the image you want to be present in the first frame. The image URL must be generated using the [GET /text_to_image_preview](/docs/api-runwayml-v1/get-runwayml-text_to_image_preview).  
  Specify `image_preview` or `image_assetId` but not both.

- `upscale` is optional. Set to `true` for 2K upscaling, default is `false` is for 720p output.  
  Supported values: `true`, `false` (default).

- `interpolate` is optional.   
  Supported values: `true` (default), `false`.

- `style` is optional. If not provided `cinematic` will be used by default.  
  Supported values: `cinematic`, `abandoned`, `abstract_sculpture`, `advertising`, `anime`, `architectural`, `cartoon`, `cine_lens`, `claymation`, `concept_art`, `digital_art`, `duotone_artistic_photo`, `forestpunk`, `frost`, `graphic_novel`, `graphite`, `impressionist_painting`, `isometric_3d`, `low_poly_3d`, `macro_photography`, `marker_drawing`, `moody_film`, `pixel_art`, `retro_photography`, `sci-fi_art`, `stickers`, `storyboard`, `actor_casting`, `thriller`, `35mm`, `3d_cartoon`, `3d_render`, `80s_vaporwave`.   
  This parameter can not be used with `image_preview` or `image_assetId`, your output will match the style of your image.

- `aspect_ratio` is optional. If not provided `16:9` will be used by default.  
  Supported values: `21:9`,`1:1`, `9:16`, `16:9`, `4:3`, `3:4`  
  This parameter can not be used with `image_preview` or `image_assetId`, your output will match the aspect ratio of your image.

- `motion` is optional. Increase or decrease the intensity of motion in your video. Higher values result in more motion. This parameter is not compatible with other motion parameters below.  
  Supported values: 1…10.

- `horizontal` is optional. Specify horizontal motion.  
  Supported values: -10…10.

- `vertical` is optional. Specify vertical motion.  
  Supported values: -10…10.

- `roll` is optional. Specify roll motion.  
  Supported values: -10…10.

- `zoom` is optional. Specify zoom motion.  
  Supported values: -10…10.

- `pan` is optional. Specify pan motion.  
  Supported values: -10…10.

- `tilt` is optional. Specify tilt motion.  
  Supported values: -10…10.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen2-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen2",
    "options": {
        "name": "<name>",
        "seconds": 4,
        "gen2Options": {
            "mode": "gen2",
            "text_prompt": "<name>",
            "seed": 45678,
            "interpolate": true,
            "upscale": true,
            "watermark": false,
            "motion_score": 6,
            "use_motion_score": true,
            "use_motion_vectors": false,
            "init_image": "<asset image url>",
            "width": 1366,
            "height": 768
        },
        "exploreMode": true,
        "assetGroupName": "Generative Video",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0.1,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen2/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
        name: string,
        seconds: number,
        gen2Options: {
            mode: string,
            text_prompt: string,
            seed: number,
            interpolate: boolean,
            upscale: boolean,
            watermark: boolean,
            use_motion_score: boolean,
            use_motion_vectors: boolean,
            motion_vector: {
                x: number,
                y: number,
                r: number,
                z: number,
                bg_x_pan: number,
                bg_y_pan: number
            },
            motion_score: number,
            init_image: string,
            image_prompt: string,
            style: string,
            width: number,
            height: number
        },
        exploreMode: boolean,
        assetGroupName: string,
        recordingEnabled: boolean
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },
    code: number,
    replyUrl: string,
    replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen2/create" \
     -d '{"image_assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const image_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen2/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  image_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
image_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen2/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "image_assetId": f"{image_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen2-extend ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen2-extend
## Extend the video by 4 seconds
<small>August 8, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-2. This endpoint no loner available.</b></span>

---

Runway [AI Tools » Audio tools » Text/Image to Video » Gen-2 » Extend Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Extending Gen-2 generations](https://help.runwayml.com/hc/en-us/articles/19207770268051-Extending-Gen-2-generations).
> **https://api.useapi.net/v1/runwayml/gen2/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of video asset you want to extend",
    "interpolate": true,
    "motion": 10,
    "horizontal": -10,
    "vertical": -5,
    "roll": -1,
    "zoom": 2,
    "pan": 5,
    "tilt": 10,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the video assetId you want extend. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).   

- `interpolate` is optional.   
  Supported values: `true` (default), `false`.

- `motion` is optional. Increase or decrease the intensity of motion in your video. Higher values result in more motion. This parameter is not compatible with other motion parameters below.  
  Supported values: 1…10.

- `horizontal` is optional. Specify horizontal motion.  
  Supported values: -10…10.

- `vertical` is optional. Specify vertical motion.  
  Supported values: -10…10.

- `roll` is optional. Specify roll motion.  
  Supported values: -10…10.

- `zoom` is optional. Specify zoom motion.  
  Supported values: -10…10.

- `pan` is optional. Specify pan motion.  
  Supported values: -10…10.

- `tilt` is optional. Specify tilt motion.  
  Supported values: -10…10.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen2-extend#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen2",
  "options": {
    "name": "<name>",
    "seconds": 4,
    "gen2Options": {
      "mode": "gen2",
      "seed": 12345678,
      "interpolate": true,
      "upscale": true,
      "watermark": false,
      "motion_score": 22,
      "use_motion_score": true,
      "use_motion_vectors": false,
      "init_video": "<original video url>",
      "extended_from_task_id": "<user:user_id-runwayml:account_email-task:parent_task_uuid>"
    },
    "exploreMode": false,
    "assetGroupName": "Generative Video",
    "recordingEnabled": true
  },
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen2/extend requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
    name: string,
    seconds: number,
    gen2Options: {
      mode: string,
      seed: number,
      interpolate: boolean,
      upscale: boolean,
      watermark: boolean,
      motion_score: number,
      use_motion_score: boolean,
      use_motion_vectors: boolean,
      motion_vector: {
        x: number,
        y: number,
        r: number,
        z: number,
        bg_x_pan: number,
        bg_y_pan: number
      },
      init_video: string,
      extended_from_task_id: string
    },
    exploreMode: boolean,
    assetGroupName: string,
    recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen2/extend" \
     -d '{"assetId": "…" }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen2/extend`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen2/extend" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-actone ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-actone
## Drive your image or video character performance using simple video and audio inputs.
<small>October 28, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Runway [Generate Video » Gen-3 Alpha » Act-One](https://app.runwayml.com/video-tools/ai-tools/generative-video). 

[Creating with Act-One on Gen-3 Alpha and Turbo](https://help.runwayml.com/hc/en-us/articles/33927968552339-Creating-with-Act-One-on-Gen-3-Alpha-and-Turbo).

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3/actone**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "driving_assetId": "Required assetId of the video asset you want to use to drive performance",
    "character_assetId": "Required assetId of the image or video asset for your character reference",
    "exploreMode": true,
    "motion_multiplier": 5,
    "aspect_ratio": "portrait",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```

- `driving_assetId` is **required**. Specify the video asset you want to use to drive performance. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `character_assetId` is **required**. Specify the image or video asset for your character reference. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image or video assets. 

- `motion_multiplier` is optional. Higher values allow for more expressive motion while lower values result in more stability.   
  Valid range: 1…5, default 3.
  
- `aspect_ratio` is optional. This parameter is only applicable for image `character_assetId`, video `character_assetId` will retain the original format.   
  Supported values: `landscape` (default), `portrait`.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-actone#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a",
  "options": {
      "name": "<name>",
      "driving_video": "<driving video url>",
      "character_image": "<character image url>",
      "motion_multiplier": 3,
      "seed": 0,
      "seconds": 5,
      "exploreMode": true,
      "watermark": false,
      "width": 1280,
      "height": 768,
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3/actone requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string
  id: string
  name: string
  image: any
  createdAt: string
  updatedAt: string
  taskType: string
  options: {
      name: string
      seed: number
      exploreMode: boolean
      watermark: boolean
      seconds: number
      driving_video: string
      character_image: string
      character_video: string
      motion_multiplier: number      
      width: number
      height: number
      flip: boolean
      assetGroupName: string
      recordingEnabled: boolean
  }
  status: string
  progressText: any
  progressRatio: any
  estimatedTimeToStartSeconds: number
  artifacts: any[]
  sharedAsset: any
  error: {
    errorMessage: string
    reason: string
    message: string
    moderation_category: string
    tally_asimov: boolean
  }
  replyUrl: string
  replyRef: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3/actone" \
     -d '{"driving_assetId": "…", "character_assetId": "…"}'
```

**JavaScript**
``` javascript
const driving_assetId = "video asset you want to use to drive performance";      
const character_assetId = "image or video asset for your character reference";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3/actone`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  driving_assetId, character_assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
driving_assetId = "video asset you want to use to drive performance"
character_assetId = "image or video asset for your character reference"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3/actone" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "driving_assetId": f"{driving_assetId}",
    "character_assetId": f"{character_assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-create
## Create a video using text and/or image prompts
<small>August 8, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Runway [Generate Video » Gen-3 Alpha](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Gen-3 Alpha](https://help.runwayml.com/hc/en-us/articles/30266515017875-Creating-with-Gen-3-Alpha).

Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases.

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional Runway API account email",
    "image_assetId": "Optional assetId of image asset",
    "text_prompt": "Optional text prompt",
    "enhance_prompt": true,
    "image_as_end_frame": false,
    "seconds": 5,
    "seed": 12345678
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```
- `email` is optional, if not provided and parameter `image_assetId` is not specified API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts).  

- `image_assetId` is optional. Specify the image assetId you want to be present in the first frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Currently Runway only supports image sizes up to `1280x768` maximum. All other images will be cropped to fit `1280x768`. You may want to upscale/downscale your image using [image_upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) to achieve the best results.

- `text_prompt` is optional. Describe your shot. [Gen-3 Alpha Prompting Guide](https://help.runwayml.com/hc/en-us/articles/30586818553107-Gen-3-Alpha-Prompting-Guide).

- `enhance_prompt` is optional.  
  Supported values: `true` (default), `false`.

- `image_as_end_frame` is optional.  Use provided above image as a last frame.   
  Supported values: `true`, `false` (default).

- `seconds` is optional. Specify desired length of the video in seconds.  
  Supported values: `5` (default), `10`.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `resolution` is optional.   
  Supported values: `720p` (default).

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen3a",
    "options": {
        "name": "<name>",
        "seconds": 10,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "enhance_prompt": true,
        "image_as_end_frame": true,
        "init_image": "<asset image url>",
        "width": 1280,
        "height": 768,
        "assetGroupName": "Generative Video",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [gen3/create](#create-a-video-using-text-andor-image-prompts) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
        name: string,
        seconds: number,
        text_prompt: string,
        init_image: string,
        seed: number,
        exploreMode: boolean,
        watermark: boolean,
        enhance_prompt: boolean,
        image_as_end_frame: boolean,
        flip: boolean,
        width: number,
        height: number,
        assetGroupName: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },  
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3/create" \
     -d '{"image_assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const image_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  image_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
image_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "image_assetId": f"{image_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-extend ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-extend
## Extend the Gen-3 Alpha video by 5 or 10 seconds
<small>August 31, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Completed Gen-3 Alpha generations can be extended up to three times to create a longer video to a maximum of 40 seconds given that the original video was 10 seconds.

Runway [Generate Video » Gen-3 Alpha » Extend Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Text/Image to Video on Gen-3 Alpha and Turbo](https://help.runwayml.com/hc/en-us/articles/30266515017875-Creating-with-Text-Image-to-Video-on-Gen-3-Alpha-and-Turbo)

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

NOTE: To extent Gen-3 Alpha Turbo use [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend).
> **https://api.useapi.net/v1/runwayml/gen3/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of Gen-3 Alpha video asset you want to extend",
    "text_prompt": "Optional text prompt",
    "seconds": 10,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the Gen-3 Alpha video assetId you want extend. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `text_prompt` is optional. Describe your shot. [Gen-3 Alpha Prompting Guide](https://help.runwayml.com/hc/en-us/articles/30586818553107-Gen-3-Alpha-Prompting-Guide).

- `seconds` is optional. How many seconds should the original video be extended by.  
  Supported values: `5` (default), `10`.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-extend#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a",
  "options": {
      "name": "<name>",
      "text_prompt": "<your text prompt>",
      "seed": 123456789,
      "seconds": 10,
      "exploreMode": true,
      "watermark": false,
      "init_video": "<original video url>",
      "extended_from_task_id": "<user:user_id-runwayml:account_email-task:parent_task_uuid>",
      "image_as_end_frame": false,
      "assetGroupName": "Generative Video",
      "extended_count": 1,
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3/extend requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
      name: string,
      seed: number,
      exploreMode: boolean,
      watermark: boolean,
      seconds: number,
      text_prompt: string,
      init_video: string,
      extended_from_task_id: string
      image_as_end_frame: boolean,
      extended_count: number,
      assetGroupName: string,
      recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3/extend" \
     -d '{"assetId": "…" }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3/extend`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3/extend" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-video ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-video
## Gen-3 Alpha Video to Video
<small>August 8, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Runway [Generate Video » Gen-3 Alpha » Video to Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

Please make sure to check official tutorial [Creating with Video to Video](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo).

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3/video**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of video asset you want to edit",
    "text_prompt": "Required text prompt",
    "structure_transformation": 9,
    "seconds": 10,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the video assetId you want to edit. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. Video to Video currently supports 16:9 aspect ratios. If using a video in a different aspect ratio it will be cropped into the supported 16:9 format. 

- `text_prompt` is **required**. Describe desired changes. [Creating with Video to Video](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo).

- `imageAssetId` is optional. Specify the restyled first frame assetId. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. See official [article](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo#h_01JMZXC16KYEMAJGMQCCR2W428). 

- `structure_transformation` is optional. Higher values result in greater change to your input’s structure, while lower values will be closer to your input.    
  Valid range: 0…10, default `3`.

- `seconds` is optional. Specify the desired length of the final video in seconds. If not provided, the value will be taken from the asset's `metadata.duration`. If the asset does not have a duration specified, it will default to `10` seconds.

- `resolution` is optional.   
  Supported values: `720p` (default).

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-video#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a",
  "options": {
      "name": "<name>",
      "video_prompt": "<asset url>",
      "video_prompt_preview_image": "<asset image url>",
      "text_prompt": "<your text prompt>",
      "structure_transformation": 0.9,
      "seed": 123456789,
      "seconds": 10,
      "width": 1280,
      "height": 768,      
      "exploreMode": true,
      "watermark": false,
      "image_as_end_frame": false,
      "enhance_prompt": true,
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3/video requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
      name: string,
      seed: number,
      exploreMode: boolean,
      watermark: boolean,
      seconds: number,
      width: number,
      height: number,    
      structure_transformation: number,
      text_prompt: string,
      video_prompt: string,
      enhance_prompt: boolean,
      assetGroupName: string,
      recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3/video" \
     -d '{"assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const text_prompt = "text prompt";
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3/video`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
text_prompt = "text prompt"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3/video" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}",
    "text_prompt": f"{text_prompt}"    
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale
## Upscale to 4K the Gen-3 Alpha and Gen-3 Alpha Turbo videos
<small>January 10, 2025 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Use this endpoint to Upscale to 4K videos generated by

* [gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](/docs/api-runwayml-v1/post-runwayml-gen3-actone)
> **https://api.useapi.net/v1/runwayml/gen3alpha/upscale**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of Gen-3 Alpha or Gen-3 Alpha Turbo video asset you want to upscale",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the Gen-3 Alpha or Gen-3 Alpha Turbo video assetId you want upscale. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2025-01-10T02:55:10.654Z",
    "updatedAt": "2025-01-10T02:55:10.691Z",
    "taskType": "harrods",
    "options": {
        "name": "<name>",
        "task_artifact_id": "<uuid>",
        "exploreMode": true,
        "asset_url": "https://runway-...mp4",
        "asset_type": "video",
        "scale_factor": 4,
        "video_name": "<video name>",
        "parent_asset_group_id": "<uuid>",
        "asset_preview_urls": [
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg"
        ]
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3alpha/upscale requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    id: string
    taskId: string
    name: string
    image: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        task_artifact_id: string
        exploreMode: boolean
        asset_url: string
        asset_type: string
        scale_factor: number
        video_name: string
        parent_asset_group_id: string
        asset_preview_urls: string[]
    }
    status: string
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },
    progressText: string 
    progressRatio: number
    estimatedTimeToStartSeconds: number
    artifacts: any[]
    sharedAsset: any
    sourceAssetId: any
    code: number
    replyUrl: string
    replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3alpha/upscale" \
     -d '{"assetId": "…" }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3alpha/upscale`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3alpha/upscale" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone
## Drive your image or video character performance using simple video and audio inputs.
<small>October 28, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

<span class="required-input-field"><b>Gen-4 Act-Two is now available.</b></span> 
> For the latest features and improved performance, consider using [POST gen4/act-two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two) instead.

Runway [Generate Video » Gen-3 Alpha » Act-One](https://app.runwayml.com/video-tools/ai-tools/generative-video). 

[Creating with Act-One on Gen-3 Alpha and Turbo](https://help.runwayml.com/hc/en-us/articles/33927968552339-Creating-with-Act-One-on-Gen-3-Alpha-and-Turbo).

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3turbo/actone**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "driving_assetId": "Required assetId of the video asset you want to use to drive performance",
    "character_assetId": "Required assetId of the image or video asset for your character reference",
    "exploreMode": true,
    "motion_multiplier": 5,
    "aspect_ratio": "portrait",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```

- `driving_assetId` is **required**. Specify the video asset you want to use to drive performance. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `character_assetId` is **required**. Specify the image or video asset for your character reference. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image or video assets. 

- `motion_multiplier` is optional. Higher values allow for more expressive motion while lower values result in more stability.   
  Valid range: 1…5, default 3.
  
- `aspect_ratio` is optional. This parameter is only applicable for image `character_assetId`, video `character_assetId` will retain the original format.   
  Supported values: `landscape` (default), `portrait`.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a",
  "options": {
      "name": "<name>",
      "driving_video": "<driving video url>",
      "character_image": "<character image url>",
      "motion_multiplier": 3,
      "seed": 0,
      "seconds": 5,
      "exploreMode": true,
      "watermark": false,
      "width": 1280,
      "height": 768,
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3turbo/actone requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string
  id: string
  name: string
  image: any
  createdAt: string
  updatedAt: string
  taskType: string
  options: {
      name: string
      seed: number
      exploreMode: boolean
      watermark: boolean
      seconds: number
      driving_video: string
      character_image: string
      character_video: string
      motion_multiplier: number      
      width: number
      height: number
      flip: boolean
      assetGroupName: string
      recordingEnabled: boolean
  }
  status: string
  progressText: any
  progressRatio: any
  estimatedTimeToStartSeconds: number
  artifacts: any[]
  sharedAsset: any
  error: {
    errorMessage: string
    reason: string
    message: string
    moderation_category: string
    tally_asimov: boolean
  }
  replyUrl: string
  replyRef: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3turbo/actone" \
     -d '{"driving_assetId": "…", "character_assetId": "…"}'
```

**JavaScript**
``` javascript
const driving_assetId = "video asset you want to use to drive performance";      
const character_assetId = "image or video asset for your character reference";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/actone`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  driving_assetId, character_assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
driving_assetId = "video asset you want to use to drive performance"
character_assetId = "image or video asset for your character reference"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/actone" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "driving_assetId": f"{driving_assetId}",
    "character_assetId": f"{character_assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-create
## Create a video using the first/middle/last image(s) with a text prompt and a camera control
<small>August 16, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Runway [Generate Video » Gen-3 Alpha Turbo](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Gen-3 Alpha](https://help.runwayml.com/hc/en-us/articles/30266515017875-Creating-with-Gen-3-Alpha).

**Gen-3 Alpha Turbo** provides significantly faster generation times with [50% cost reduction](https://help.runwayml.com/hc/en-us/articles/15124877443219-How-do-credits-work), at 5 credits per second of video generation. 

You can provide both first and last image inputs in horizontal or vertical aspect ratios.

**Gen-3 Alpha Turbo** is supported with free accounts and is *the only way* to experience Runway Gen-3 Alpha if you have a free account.

Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases.

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3turbo/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "firstImage_assetId": "Optional assetId of first image asset",
    "middleImage_assetId": "Optional assetId of middle image asset",
    "lastImage_assetId": "Optional assetId of last image asset",
    "text_prompt": "Optional text prompt",
    "aspect_ratio": "portrait",
    "seconds": 5,
    "seed": 12345678
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `firstImage_assetId` is optional. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Currently Runway only supports image sizes up to `1280x768` or `768x1280` maximum. All other images will be cropped to fit supported sizes. You may want to upscale/downscale your image using [image_upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) to achieve the best results.   

- `middleImage_assetId` is optional. Specify the image assetId you want to be present in the **middle** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Currently Runway only supports image sizes up to `1280x768` or `768x1280` maximum. All other images will be cropped to fit supported sizes. You may want to upscale/downscale your image using [image_upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) to achieve the best results.   

- `lastImage_assetId` is optional. Specify the image assetId you want to be present in the **last** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Currently Runway only supports image sizes up to `1280x768` or `768x1280` maximum. All other images will be cropped to fit supported sizes. You may want to upscale/downscale your image using [image_upscaler](/docs/api-runwayml-v1/get-runwayml-image_upscaler) to achieve the best results.   

- `text_prompt` is optional. Describe your shot. [Gen-3 Alpha Prompting Guide](https://help.runwayml.com/hc/en-us/articles/30586818553107-Gen-3-Alpha-Prompting-Guide).

- `aspect_ratio` is optional.  
  Supported values: `landscape` (default), `portrait`.  

- `horizontal` is optional. Specify horizontal motion.  
  Supported values: -10…10.

- `vertical` is optional. Specify vertical motion.  
  Supported values: -10…10.

- `roll` is optional. Specify roll motion.  
  Supported values: -10…10.

- `zoom` is optional. Specify zoom motion.  
  Supported values: -10…10.

- `pan` is optional. Specify pan motion.  
  Supported values: -10…10.

- `tilt` is optional. Specify tilt motion.  
  Supported values: -10…10.

- `static` is optional. Set to `true` to keep the camera as still as possible. Not compatible with other motion parameters.

- `seconds` is optional. Specify desired length of the video in seconds.  
  Supported values: `5` (default), `10`.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

**Notes:**  
- At least one of `firstImage_assetId`, `middleImage_assetId` or `lastImage_assetId` must be provided.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen3a_turbo",
    "options": {
        "name": "<name>",
        "seconds": 10,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "enhance_prompt": true,
        "flip": true,
        "keyframes": [
            {
                "image": "<first image url>",
                "timestamp": 0
            },
            {
                "image": "<middle image url>",
                "timestamp": 0.5
            },
            {
                "image": "<last image url>",
                "timestamp": 1
            }
        ],
        "assetGroupName": "Generative Video",
        "init_image": "<image url>",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3turbo/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
        name: string,
        seconds: number,
        text_prompt: string,
        seed: number,
        exploreMode: boolean,
        watermark: boolean,
        enhance_prompt: boolean,
        keyframes: { image: string, timestamp: number }[],
        flip: boolean,
        camera: {
            x: number,
            y: number,
            r: number,
            z: number,
            bg_x_pan: number,
            bg_y_pan: number,
            static: boolean
        },        
        assetGroupName: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },  
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3turbo/create" \
     -d '{"firstImage_assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const firstImage_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  firstImage_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
firstImage_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "firstImage_assetId": f"{firstImage_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand
## Expand Video (outpaint) with Gen-3 Alpha Turbo
<small>November 25, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Expand Video reimagines and reframes existing videos into different formats.  

Runway [Generate Video » Gen-3 Alpha Turbo » Expand Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Expand Video on Gen-3 Alpha Turbo](https://help.runwayml.com/hc/en-us/articles/34926355398675-Creating-with-Expand-Video-on-Gen-3-Alpha-Turbo)

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  
> **https://api.useapi.net/v1/runwayml/gen3turbo/expand**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "videoAssetId": "Required video asset you want to expand",
    "imageAssetId": "Optional image asset to be used as video first frame",
    "text_prompt": "Optional text prompt",
    "seconds": 10,
    "seed": 12345678,
    "outpaint_aspect_ratio": "portrait",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `videoAssetId` is **required**. Specify the video asset you want expand. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `imageAssetId` is optional. Use an outpainted image of the video’s first frame for best results when using a guiding image. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets.  

- `text_prompt` is optional. Expand Video works great in most cases without a prompt. Include a text or image prompt for more control. [Creating with Expand Video on Gen-3 Alpha Turbo](https://help.runwayml.com/hc/en-us/articles/34926355398675-Creating-with-Expand-Video-on-Gen-3-Alpha-Turbo).

- `outpaint_aspect_ratio` is optional. Specify desired output aspect ratio.   
  Supported values: `landscape` (default), `portrait`.  

- `seconds` is optional. Video asset `metadata.duration` will be used, if not provided will be defaulted to `10`.  
  Supported values: `5`, `10` (default).  

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video `videoAssetId` account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a_turbo",
  "options": {
      "name": "<name>",
      "text_prompt": "<your text prompt>",
      "seed": 123456789,
      "seconds": 10,
      "exploreMode": true,
      "watermark": false,
      "outpaint_input_video": "<original video url>",
      "outpaint_input_video_preview_image": "<preview image url>",
      "outpaint_guiding_image": "<first frame image url>",
      "outpaint_aspect_ratio": "3:5",
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve videoAssetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3turbo/expand requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
      name: string,
      seed: number,
      exploreMode: boolean,
      watermark: boolean,
      seconds: number,
      text_prompt: string,
      outpaint_input_video: string,
      outpaint_input_video_preview_image: string,
      outpaint_guiding_image: string,
      outpaint_aspect_ratio: string,
      assetGroupName: string,
      recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3turbo/expand" \
     -d '{"videoAssetId": "…" }'
```

**JavaScript**
``` javascript
const videoAssetId = "video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/expand`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  videoAssetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoAssetId = "video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/expand" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "videoAssetId": f"{videoAssetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend
## Extend the Gen-3 Alpha Turbo video by 8 seconds
<small>November 5, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Completed Gen-3 Alpha Turbo generations can be extended up to three times to create a longer video to a maximum of 34 seconds given that the original video was 10 seconds.

Runway [Generate Video » Gen-3 Alpha Turbo » Extend Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Text/Image to Video on Gen-3 Alpha and Turbo](https://help.runwayml.com/hc/en-us/articles/30266515017875-Creating-with-Text-Image-to-Video-on-Gen-3-Alpha-and-Turbo)

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

NOTE: To extent Gen-3 Alpha use [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend).
> **https://api.useapi.net/v1/runwayml/gen3turbo/extend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of Gen-3 Alpha Turbo video asset you want to extend",
    "text_prompt": "Optional text prompt",
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the Gen-3 Alpha Turbo video assetId you want extend. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `text_prompt` is optional. Describe your shot. [Gen-3 Alpha Prompting Guide](https://help.runwayml.com/hc/en-us/articles/30586818553107-Gen-3-Alpha-Prompting-Guide).

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a_turbo",
  "options": {
      "name": "<name>",
      "text_prompt": "<your text prompt>",
      "seed": 123456789,
      "seconds": 10,
      "exploreMode": true,
      "watermark": false,
      "init_video": "<original video url>",
      "extended_from_task_id": "<user:user_id-runwayml:account_email-task:parent_task_uuid>",
      "assetGroupName": "Generative Video",
      "extended_count": 1,
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3turbo/extend requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
      name: string,
      seed: number,
      exploreMode: boolean,
      watermark: boolean,
      seconds: number,
      text_prompt: string,
      init_video: string,
      extended_from_task_id: string
      extended_count: number,
      assetGroupName: string,
      recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3turbo/extend" \
     -d '{"assetId": "…" }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/extend`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/extend" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-video ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-video
## Gen-3 Alpha Turbo Video to Video
<small>November 4, 2024 (December 15, 2025)</small>

<span class="required-input-field"><b>Runway website no longer supports Gen-3. Consider migrating to Gen-4.x.</b></span>

---

Runway [Generate Video » Gen-3 Alpha Turbo » Video to Video](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

Please make sure to check official tutorial [Creating with Video to Video](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo).

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen3turbo/video**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of video asset you want to edit",
    "text_prompt": "Required text prompt",
    "aspect_ratio": "portrait",
    "structure_transformation": 9,
    "seconds": 10,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the video assetId you want to edit. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. Video to Video currently supports 16:9 aspect ratios. If using a video in a different aspect ratio it will be cropped into the supported 16:9 format. 

- `text_prompt` is **required**. Describe desired changes. [Creating with Video to Video](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo).

- `imageAssetId` is optional. Specify the restyled first frame assetId. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. See official [article](https://help.runwayml.com/hc/en-us/articles/33350169138323-Creating-with-Video-to-Video-on-Gen-3-Alpha-and-Turbo#h_01JMZXC16KYEMAJGMQCCR2W428). 

- `structure_transformation` is optional. Higher values result in greater change to your input’s structure, while lower values will be closer to your input.    
  Valid range: 0…10, default `3`.

- `aspect_ratio` is optional.  
  Supported values: `landscape` (default), `portrait`.  

- `seconds` is optional. Specify the desired length of the final video in seconds. If not provided, the value will be taken from the asset's `metadata.duration`. If the asset does not have a duration specified, it will default to `10` seconds.

- `resolution` is optional.   
  Supported values: `720p` (default).

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "gen3a_turbo",
  "options": {
      "name": "<name>",
      "video_prompt": "<video asset url>",
      "video_prompt_preview_image": "<asset image url>",
      "text_prompt": "<your text prompt>",
      "structure_transformation": 0.9,
      "flip": true,
      "width": 768,
      "height": 1280,      
      "seed": 123456789,
      "seconds": 10,
      "exploreMode": true,
      "watermark": false,
      "enhance_prompt": true,
      "assetGroupName": "Generative Video",
      "recordingEnabled": true
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen3turbo/video requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
      name: string,
      seed: number,
      exploreMode: boolean,
      watermark: boolean,
      seconds: number,
      flip: boolean,
      width: number,
      height: number,    
      structure_transformation: number,
      text_prompt: string,
      video_prompt: string,      
      enhance_prompt: boolean,
      assetGroupName: string,
      recordingEnabled: boolean
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen3turbo/video" \
     -d '{"assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const text_prompt = "text prompt";
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/video`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
text_prompt = "text prompt"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/video" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}",
    "text_prompt": f"{text_prompt}"    
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice
## Create Act-Two voice swap
<small>September 8, 2025</small>

---

Runway [Generate Video » Gen-4 or Gen-4 Turbo » Act-Two](https://app.runwayml.com/video-tools/teams/ai-tools/generate). 

[Creating with Act-Two](https://help.runwayml.com/hc/en-us/articles/42311337895827-Creating-with-Act-Two).

Please be aware that Runway's moderation system analyzes your video assets and may fail task with moderation message if the content is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4/act-two-voice**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "video_assetId": "Required assetId of the video asset (3-30 seconds) for voice swap",
    "voiceId": "Required voice ID from available voices",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `video_assetId` is **required**. Specify the video asset (3-30 seconds duration) you want to apply voice swap to. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).  

- `voiceId` is **required**. Specify the voice ID to use for voice swap. Use [GET /lipsync/voices](/docs/api-runwayml-v1/get-runwayml-lipsync-voices) to see the list of available voices.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "id": "<uuid>",
    "name": "<voice_name>_<video_name>",
    "image": null,
    "createdAt": "2025-09-08T06:52:26.378Z",
    "updatedAt": "2025-09-08T06:52:26.468Z",
    "taskType": "workflow_s2s_video",
    "options": {
        "name": "<voice_name>_<video_name>",
        "video": "<video url>",
        "voiceId": "<voice id>",
        "seconds": 15,
        "exploreMode": false,
        "assetGroupId": "<uuid>"
    },  
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": "0",
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen4/act-two-voice requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string
    id: string
    name: string
    image: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        video: string
        voiceId: string
        seconds: number
        exploreMode: boolean
        assetGroupId: string
    }
    status: string
    progressText: any
    progressRatio: string
    estimatedTimeToStartSeconds: number
    artifacts: any[]
    sharedAsset: any
    sourceAssetId: any
    error: {
      errorMessage: string
      reason: string
      message: string
      moderation_category: string
      tally_asimov: boolean
    }
    code: number
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/act-two-voice" \
     -d '{"video_assetId": "…", "voiceId": "…"}'
```

**JavaScript**
``` javascript
const video_assetId = "video asset (3-30 seconds) for voice swap";      
const voiceId = "voice ID from available voices";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/act-two-voice`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  video_assetId, voiceId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
video_assetId = "video asset (3-30 seconds) for voice swap"
voiceId = "voice ID from available voices"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/act-two-voice" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "video_assetId": f"{video_assetId}",
    "voiceId": f"{voiceId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two
## Create Act-Two videos using Gen-4 with driving video and character reference.
<small>July 22, 2025</small>

---

Runway [Generate Video » Gen-4 or Gen-4 Turbo » Act-Two](https://app.runwayml.com/video-tools/teams/ai-tools/generate). 

[Creating with Act-Two](https://help.runwayml.com/hc/en-us/articles/42311337895827-Creating-with-Act-Two).

Please be aware that Runway's moderation system analyzes your image and video assets and may fail task with moderation message if the content is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4/act-two**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "driving_assetId": "Required assetId of the video asset (3-30 seconds) to drive performance",
    "character_assetId": "Required assetId of the image or video asset for character reference",
    "aspect_ratio": "16:9",
    "body_control": true,
    "expression_intensity": 3,
    "seed": 12345,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `driving_assetId` is **required**. Specify the video asset (3-30 seconds duration) you want to use to drive performance. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).  

- `character_assetId` is **required**. Specify the image or video asset for your character reference. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image or video assets. To upload a new image or video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).  

- `aspect_ratio` is optional. Controls the output video dimensions.   
  Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.  

- `body_control` is optional. Controls body movement tracking.   
  Default: `true`.

- `expression_intensity` is optional. Controls the intensity of facial expressions.   
  Valid range: 1…5, default: 3.

- `seed` is optional. Use the same seed to get reproducible results. If not provided, a random seed will be generated.   
  Valid range: 1…2147483647.

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-act-two#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "id": "<uuid>",
    "name": "Act-Two <driving_video_name>_<character_asset_name>",
    "image": null,
    "createdAt": "2025-07-22T06:52:26.378Z",
    "updatedAt": "2025-07-22T06:52:26.468Z",
    "taskType": "act_two",
    "options": {
        "name": "Act-Two <driving_video_name>_<character_asset_name>",
        "driving_video": "<driving video url>",
        "character_image": "<character image url>",
        "character_video": "<character video url>",
        "seconds": 6,
        "exploreMode": false,
        "height": 720,
        "width": 1280,
        "seed": 2830268783,
        "watermark": false,
        "body_control": true,
        "expression_intensity": 1,
        "assetGroupId": "<uuid>",
        "recordingEnabled": true
    },  
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": "0",
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [gen4/act-two](#create-act-two-videos-using-gen-4-with-driving-video-and-character-reference) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string
    id: string
    name: string
    image: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        driving_video: string
        character_image: string
        character_video: string
        seconds: number
        exploreMode: boolean
        height: number
        width: number
        seed: number
        watermark: boolean
        body_control: boolean
        expression_intensity: number
        assetGroupId: string
        recordingEnabled: boolean
    }
    status: string
    progressText: any
    progressRatio: string
    estimatedTimeToStartSeconds: number
    artifacts: any[]
    sharedAsset: any
    sourceAssetId: any
    error: {
      errorMessage: string
      reason: string
      message: string
      moderation_category: string
      tally_asimov: boolean
    }
    code: number
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/act-two" \
     -d '{"driving_assetId": "…", "character_assetId": "…"}'
```

**JavaScript**
``` javascript
const driving_assetId = "video asset (3-30 seconds) to drive performance";      
const character_assetId = "image or video asset for character reference";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/act-two`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  driving_assetId, character_assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
driving_assetId = "video asset (3-30 seconds) to drive performance"
character_assetId = "image or video asset for character reference"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/act-two" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "driving_assetId": f"{driving_assetId}",
    "character_assetId": f"{character_assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create
## Create a video using the first image(s) with a text prompt
<small>April 2, 2025 (July 22, 2025)</small>

---

Runway [Generate Video » Gen-4](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4).

Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases.

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "firstImage_assetId": "Required assetId of first image asset",
    "text_prompt": "Optional text prompt",
    "aspect_ratio": "3:4",
    "seconds": 5,
    "seed": 12345678
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `firstImage_assetId` is **required**. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `text_prompt` is optional. Describe your shot. [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4).  
  Maximum length: 1000 characters.  

- `aspect_ratio` is optional.  
  Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.

- `seconds` is optional. Specify desired length of the video in seconds.  
  Supported values: `5` (default), `10`.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen4",
    "options": {
        "name": "<name>",
        "route": "i2v",
        "seconds": 10,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "assetGroupName": "Generative Video",
        "init_image": "<image url>",
        "width": 832,
        "height": 1104,        
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen4/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
          name: string,
          seconds: number,
          text_prompt: string,
          seed: number,
          exploreMode: boolean,
          watermark: boolean,
          enhance_prompt: boolean,
          route: string,
          init_image: string,
          assetGroupId: string,
          assetGroupName: string,
          recordingEnabled: boolean
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },  
    code: number,
    replyUrl: string,
    replyRef: string
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/create" \
     -d '{"firstImage_assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const firstImage_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  firstImage_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
firstImage_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "firstImage_assetId": f"{firstImage_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-upscale ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-upscale
## Upscale to 4K the Gen-4, Gen-4 Turbo, Gen-3 Alpha and Gen-3 Alpha Turbo videos
<small>April 7, 2025 (July 22, 2025)</small>

---

Use this endpoint to Upscale to 4K videos generated by

* [gen4turbo/create](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create)
* [gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create)
* [gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](/docs/api-runwayml-v1/post-runwayml-gen3-actone)
> **https://api.useapi.net/v1/runwayml/gen4/upscale**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of Gen-3 Alpha or Gen-3 Alpha Turbo video asset you want to upscale",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the Gen-4, Gen-4 Turbo, Gen-3 Alpha or Gen-3 Alpha Turbo video assetId you want upscale. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-upscale#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2025-01-10T02:55:10.654Z",
    "updatedAt": "2025-01-10T02:55:10.691Z",
    "taskType": "media_upscale",
    "options": {
        "name": "<name>",
        "task_artifact_id": "<uuid>",
        "exploreMode": true,
        "asset_url": "https://runway-...mp4",
        "asset_type": "video",
        "scale_factor": 4,
        "video_name": "<video name>",
        "parent_asset_group_id": "<uuid>",
        "asset_preview_urls": [
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg",
            "https://runway-...jpg"
        ]
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen4/upscale requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    id: string
    taskId: string
    name: string
    image: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        task_artifact_id: string
        exploreMode: boolean
        asset_url: string
        asset_type: string
        scale_factor: number
        video_name: string
        parent_asset_group_id: string
        asset_preview_urls: string[]
    }
    status: string
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },
    progressText: string 
    progressRatio: number
    estimatedTimeToStartSeconds: number
    artifacts: any[]
    sharedAsset: any
    sourceAssetId: any
    code: number
    replyUrl: string
    replyRef: string
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/upscale" \
     -d '{"assetId": "…" }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/upscale`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/upscale" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-video ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-video
## Create a video using Runway Gen-4 Aleph (video-to-video)
<small>August 4, 2025</small>

---

[Creating with Aleph](https://help.runwayml.com/hc/en-us/articles/43176400374419-Creating-with-Aleph).

Gen-4 Aleph is Runway's video-to-video generation model that allows you to transform an input video using text prompts and optional image conditioning. 

Please be aware that Runway's moderation system analyzes your video and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4/video**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "video_assetId": "Required assetId of video asset",
    "image_assetId": "Optional assetId of image asset",
    "text_prompt": "Required text prompt describing the transformation",
    "seed": 12345678,
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `video_assetId` is **required**. Specify the video assetId you want to transform. The video must have duration, width, and height metadata. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `image_assetId` is optional. Specify an image assetId to use as additional conditioning for the video transformation. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets.

- `text_prompt` is **required**. Describe the desired transformation or style for the video. [Creating with Aleph](https://help.runwayml.com/hc/en-us/articles/43176400374419-Creating-with-Aleph).  
  Maximum length: 1000 characters.  

- `seed` is optional. Random seed for reproducible results.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-video#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen4_aleph",
    "options": {
        "name": "<name>",
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "seconds": 5,
        "width": 1280,
        "height": 720,
        "video": "<input video url>",
        "images": ["<optional image url>"],
        "imageAssetIds": ["<optional image asset id>"],
        "assetGroupId": "<asset group id>",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [gen4/video](#create-a-video-using-runway-gen-4-aleph-video-to-video) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
          name: string,
          text_prompt: string,
          seed: number,
          exploreMode: boolean,
          watermark: boolean,
          seconds: number,
          width: number,
          height: number,
          video: string,
          images: string[],
          imageAssetIds: string[],
          assetGroupId: string,
          recordingEnabled: boolean
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },  
    code: number,
    replyUrl: string,
    replyRef: string
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/video" \
     -d '{"video_assetId": "…", "text_prompt": "transform this video into a cinematic scene"}'
```

**JavaScript**
``` javascript
const video_assetId = "assetId of video asset";      
const text_prompt = "transform this video into a cinematic scene";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/video`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  video_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
video_assetId = "assetId of video asset"      
text_prompt = "transform this video into a cinematic scene"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/video" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "video_assetId": f"{video_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4_5-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4_5-create
## Create a video using text prompt or image
<small>December 15, 2025 (January 23, 2026)</small>

---

Runway [Generate Video » Gen-4.5](https://app.runwayml.com/video-tools/ai-tools/generative-video).

Gen-4.5 supports two modes:
- **Text-to-Video (T2V)**: Generate 720p 16:9 videos from text prompts
- **Image-to-Video (I2V)**: Generate videos from a first image with optional text prompt, supporting multiple aspect ratios

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4_5/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body

**Text-to-Video (T2V)**
```json
{
    "email": "Optional Runway account email",
    "text_prompt": "Required text prompt for T2V",
    "seconds": 5,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

**Image-to-Video (I2V)**
```json
{
    "firstImage_assetId": "Required assetId of first image asset",
    "text_prompt": "Optional text prompt",
    "aspect_ratio": "9:16",
    "seconds": 5,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `email` is optional. If not specified, the API will randomly select an available account with capacity for load balancing. Use [GET /accounts](/docs/api-runwayml-v1/get-runwayml-accounts) to see the list of linked Runway accounts. Not used when `firstImage_assetId` is provided (account is determined by the asset).

- `firstImage_assetId` is optional. When provided, enables **Image-to-Video** mode. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).

- `text_prompt` is **required for T2V**, optional for I2V. Describe your video scene.
  Maximum length: 5000 characters.

- `aspect_ratio` is optional, **I2V only**. Ignored for T2V which is always 16:9.
  Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.

- `seconds` is optional. Specify desired length of the video in seconds.
  Supported values: `5` (default), `8`, `10`.

- `seed` is optional.
  Valid range 1…4294967294.

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not provided value for specified account will be used.
  Valid range: 1…10.
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.

##### Responses

**200**
**200 OK**

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4_5-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

**Text-to-Video Response**
```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2026-01-23T01:02:03.456Z",
    "updatedAt": "2026-01-23T01:02:03.456Z",
    "taskType": "gen4.5",
    "options": {
        "name": "<name>",
        "route": "t2v",
        "seconds": 5,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": false,
        "watermark": false,
        "width": 1280,
        "height": 720
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**Image-to-Video Response**
```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2026-01-23T01:02:03.456Z",
    "updatedAt": "2026-01-23T01:02:03.456Z",
    "taskType": "gen4.5",
    "options": {
        "name": "<name>",
        "route": "k2v",
        "seconds": 8,
        "text_prompt": "<your optional text prompt>",
        "seed": 12345789,
        "exploreMode": false,
        "watermark": false,
        "keyframes": [
            {
                "image": "<image url>",
                "timestamp": 0
            }
        ],
        "width": 720,
        "height": 1280
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [gen4_5/create](#create-a-video-using-text-prompt-or-image) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.

```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
          name: string,
          seconds: number,
          text_prompt: string,
          seed: number,
          exploreMode: boolean,
          watermark: boolean,
          route: string,  // "t2v" for text-to-video, "k2v" for image-to-video
          keyframes: [{   // I2V only
            image: string,
            timestamp: number
          }],
          width: number,
          height: number,
          assetGroupId: string
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },
    code: number,
    replyUrl: string,
    replyRef: string
  }
}
```

##### Examples

**Curl (T2V)**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \
     -d '{"text_prompt": "A cinematic shot of a sunset over the ocean"}'
```

**Curl (I2V)**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \
     -d '{"firstImage_assetId": "user:123-runwayml:account@email.com-asset:uuid", "text_prompt": "Camera slowly zooms out", "aspect_ratio": "9:16"}'
```

**JavaScript**
``` javascript
// Text-to-Video
const text_prompt = "A cinematic shot of a sunset over the ocean";
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4_5/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ text_prompt });
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

// Image-to-Video
const firstImage_assetId = "user:123-runwayml:account@email.com-asset:uuid";
data.body = JSON.stringify({
  firstImage_assetId,
  text_prompt: "Camera slowly zooms out",
  aspect_ratio: "9:16"
});
const i2vResponse = await fetch(apiUrl, data);
const i2vResult = await i2vResponse.json();
console.log("i2v response", {i2vResponse, i2vResult});
```

**Python**
``` python
import requests

apiUrl = "https://api.useapi.net/v1/runwayml/gen4_5/create"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}

# Text-to-Video
body_t2v = {
    "text_prompt": "A cinematic shot of a sunset over the ocean"
}
response = requests.post(apiUrl, headers=headers, json=body_t2v)
print("T2V:", response, response.json())

# Image-to-Video
body_i2v = {
    "firstImage_assetId": "user:123-runwayml:account@email.com-asset:uuid",
    "text_prompt": "Camera slowly zooms out",
    "aspect_ratio": "9:16"
}
response = requests.post(apiUrl, headers=headers, json=body_i2v)
print("I2V:", response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create
## Create a video using the first image(s) with a text prompt
<small>April 7, 2025 (July 22, 2025)</small>

---

Runway [Generate Video » Gen-4 Turbo](https://app.runwayml.com/video-tools/ai-tools/generative-video).  

[Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4).

Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases.

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/gen4turbo/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "firstImage_assetId": "Required assetId of first image asset",
    "text_prompt": "Optional text prompt",
    "aspect_ratio": "3:4",
    "seconds": 5,
    "seed": 12345678
    "exploreMode": true,    
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `firstImage_assetId` is **required**. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `text_prompt` is optional. Describe your shot. [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4).  
  Maximum length: 1000 characters.  

- `aspect_ratio` is optional.  
  Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.

- `seconds` is optional. Specify desired length of the video in seconds.  
  Supported values: `5` (default), `10`.

- `seed` is optional.    
  Valid range 1…4294967294.  

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen4_turbo",
    "options": {
        "name": "<name>",
        "route": "i2v",
        "seconds": 10,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "assetGroupName": "Generative Video",
        "init_image": "<image url>",
        "width": 832,
        "height": 1104,        
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new gen4turbo/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  task: {
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
          name: string,
          seconds: number,
          text_prompt: string,
          seed: number,
          exploreMode: boolean,
          watermark: boolean,
          enhance_prompt: boolean,
          route: string,
          init_image: string,
          assetGroupId: string,
          assetGroupName: string,
          recordingEnabled: boolean
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },  
    code: number,
    replyUrl: string,
    replyRef: string
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4turbo/create" \
     -d '{"firstImage_assetId": "…", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const firstImage_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4turbo/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  firstImage_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
firstImage_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4turbo/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "firstImage_assetId": f"{firstImage_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-images-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-images-create
## Images
<small>February 17, 2026 (April 24, 2026)</small>

---

Unified image generation endpoint supporting multiple AI models: [FLUX.2 Max](https://bfl.ai) `flux-2-max`, [FLUX.2 Klein](https://bfl.ai) `flux-2-klein`, [Nano Banana](https://deepmind.google/models/gemini/flash/) `nano-banana`, [Nano Banana 2](https://deepmind.google/models/gemini/flash/) `nano-banana-2`, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) `nano-banana-pro`, [GPT Image 1.5](https://platform.openai.com/docs/models/gpt-image-1) `gpt-image-1-5`, [GPT Image 1 Mini](https://platform.openai.com/docs/models/gpt-image-1-mini) `gpt-image-1-mini`, [GPT Image 2](https://openai.com/) `gpt-image-2`, [Seedream 5](https://www.volcengine.com/product/seedream) `seedream-5`, [Gen-4](https://runwayml.com) `gen4`, and [Gen-4 Turbo](https://runwayml.com) `gen4-turbo`.

Nano Banana, Nano Banana 2, and Nano Banana Pro support image references of famous people and minors, unlike [Google Flow](/docs/api-google-flow-v1).

Each model has different capabilities, reference image limits, resolution options, and optional parameters.

Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can set `exploreMode` to `true` to generate images without using credits. Explore mode generations are queued at lower priority and may take significantly longer — expect 5–15 minutes compared to 10–30 seconds for regular generations. All models support `exploreMode`.

##### Model Comparison: FLUX.2

| Feature | FLUX.2 Max | FLUX.2 Klein |
|---------|:----------:|:------------:|
| Reference images | 0–8 | 0–4 |
| Resolution | 1K, 2K, 4K, 0.6MP | 1K, 2K, 0.6MP |
| aspect_ratio | all incl. 9:21 | all incl. 9:21 |
| text_prompt | optional (max 4000) | optional (max 4000) |
| seed | ✓ | ✓ |

FLUX.2 uses **ordinal references** in prompts ("subject from image 1, style from image 2, background from image 3"), not `@IMG_N` tags. See the official [FLUX.2 Max prompting guide](https://docs.bfl.ai/guides/prompting_guide_flux2) and FLUX.2 Klein prompting guide for best practices.

##### Model Comparison: Nano Banana

| Feature | Nano Banana | Nano Banana 2 | Nano Banana Pro |
|---------|:-----------:|:-------------:|:---------------:|
| Reference images | 0–3 | 0–14 | 0–14 |
| Resolution | — | 1K, 2K, 4K | 1K, 2K, 4K |
| aspect_ratio | all | all | all |
| text_prompt | optional (max 5000) | optional (max 5000) | optional (max 5000) |

##### Model Comparison: GPT Image / Seedream

| Feature | GPT Image 1.5 | GPT Image 1 Mini | GPT Image 2 | Seedream 5 |
|---------|:-------------:|:----------------:|:-----------:|:----------:|
| Reference images | 0–1 | 0–1 | 0–14 | 0–14 |
| Resolution | — | — | 1K, 2K, 4K | 2K, 3K |
| aspect_ratio | 1:1, 3:2, 2:3 | 1:1, 3:2, 2:3 | all | all except 4:5, 5:4 |
| text_prompt | **required** (max 32000) | **required** (max 32000) | **required** (max 32000) | optional (max 4000) |
| quality | — | — | `low`, `medium`, `high` | — |

##### Model Comparison: Gen-4

| Feature | Gen-4 | Gen-4 Turbo |
|---------|:----:|:----------:|
| Reference images | 0–3 | **1–3** (required) |
| Resolution | 1080p, 720p | 1080p |
| text_prompt | optional (max 1000) | optional (max 1000) |
| diversity | ✓ | — |
| seed | ✓ | ✓ |
| style | ✓ | ✓ |

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/images/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "model": "nano-banana-pro",
    "email": "Optional Runway API account email",
    "text_prompt": "Required text prompt",
    "aspect_ratio": "16:9",
    "resolution": "1K",
    "num_images": 4,
    "imageAssetId1": "user:user_id-runwayml:account_email-asset:asset_uuid",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```
- `model` is **required**.
  Supported values: `flux-2-max`, `flux-2-klein`, `nano-banana`, `nano-banana-2`, `nano-banana-pro`, `gpt-image-1-5`, `gpt-image-1-mini`, `gpt-image-2`, `seedream-5`, `gen4`, `gen4-turbo`.
  See model comparison for details.

- `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts).

- `text_prompt` describes your image in detail. **Required** for `gpt-image-1-5`, `gpt-image-1-mini`, and `gpt-image-2`, optional for all other models.
  Maximum length depends on model: GPT Image family — 32000; Nano Banana family — 5000; FLUX.2 Max / Klein and Seedream 5 — 4000; Gen-4 / Gen-4 Turbo — 1000.

- `aspect_ratio` is optional. Default `16:9` (`1:1` for FLUX.2). Available values depend on model — see model comparison.
  All values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `4:5`, `5:4`, `3:2`, `2:3`, `9:21`.
  - FLUX.2 Max, FLUX.2 Klein: all values incl. `9:21`
  - GPT Image 1.5, GPT Image 1 Mini: `1:1`, `3:2`, `2:3`
  - GPT Image 2: all values
  - Seedream 5: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `3:2`, `2:3`

- `resolution` is optional. Available resolutions depend on model.
  - FLUX.2 Max: `1K` (default), `2K`, `4K`, `0.6MP`
  - FLUX.2 Klein: `1K` (default), `2K`, `0.6MP`
  - Gen-4: `1080p` (default), `720p`
  - Gen-4 Turbo: `1080p`
  - GPT Image 2: `1K` (default), `2K`, `4K`
  - Nano Banana 2, Nano Banana Pro: `1K` (default), `2K`, `4K`
  - Seedream 5: `2K` (default), `3K`
  - Nano Banana, GPT Image 1.5, GPT Image 1 Mini: not supported

- `num_images` is optional.
  Supported values: `1` (default), `4`.

- `imageAssetId1` through `imageAssetId14` are optional. Specify the assetIds of reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). For Gen-4, Seedream 5, and Nano Banana models, parameters can be referred in the prompt as `@IMG_1`, `@IMG_2`, etc. For **FLUX.2 Max and Klein** use ordinal descriptions instead ("image 1", "image 2", …) — see the [FLUX.2 prompting guide](https://docs.bfl.ai/guides/prompting_guide_flux2).
  Maximum number of reference images depends on model — see model comparison.

- `diversity` is optional. Aesthetic Range, higher values increase the creative variation between generations in a set. Only supported by Gen-4. When using reference images, defaults to 2.
  Valid range: 1…5.

- `seed` is optional. Supported by Gen-4, Gen-4 Turbo, FLUX.2 Max, and FLUX.2 Klein.
  Valid range 1…4294967294.

- `style` is optional. Supported by Gen-4 and Gen-4 Turbo.
  Supported values: `vivid`, `vivid-warm`, `vivid-cool`, `high-contrast`, `high-contrast-warm`, `high-contrast-cool`, `bw`, `bw-contrast`, `muted-pastel`, `dreamscape`, `nordic-minimal`, `light-anime`, `dark-anime`, `painted-anime`, `3d-cartoon`, `sketch`, `low-angle`, `in-motion`, `terracotta`.

- `quality` is optional. Supported only by `gpt-image-2`. Default `high`.
  Supported values: `low`, `medium`, `high`.

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.
  Valid range: 1…10.
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.

##### Responses

**200**
**200 OK**

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated images can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-images-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "task": {
        "id": "<uuid>",
        "name": "nano-banana-pro <your text prompt>",
        "image": null,
        "createdAt": "2026-02-17T23:58:27.296Z",
        "updatedAt": "2026-02-17T23:58:27.423Z",
        "taskType": "gemini_image",
        "options": {
            "name": "nano-banana-pro <your text prompt>",
            "text_prompt": "<your text prompt>",
            "reference_images": [
                {
                    "tag": "IMG_1",
                    "assetId": "<asset uuid>",
                    "url": "<asset CDN url>"
                }
            ],
            "aspect_ratio": "9:16",
            "image_size": "1K",
            "num_images": 1,
            "assetGroupId": "<uuid>",
            "creationSource": "tool-mode",
            "model": "gemini-3-pro-image-preview",
            "exploreMode": false,
            "recordingEnabled": true
        },
        "status": "PENDING",
        "error": null,
        "progressText": null,
        "progressRatio": "0",
        "estimatedTimeToStartSeconds": 0,
        "artifacts": [],
        "sharedAsset": null,
        "sourceAssetId": null,
        "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
        "code": 200
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

When `exploreMode` is `true` and another explore mode job is still running, the new job will not start until the current one completes. Since explore mode generations can take **5–15 minutes**, you may need to wait significantly longer before retrying.

There are two possible cases for API response 429:

* API query is full and can not accept new [images/create](#images) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.

```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
        name: string,
        text_prompt: string,
        aspect_ratio: string,
        num_images: number,
        exploreMode: boolean,
        seed: number,
        diversity: number,
        style: string,
        width: number,
        height: number,
        flip: boolean,
        model: string,
        image_size: string,
        reference_images: { assetId: string, url: string, tag: string }[],
        creationSource: string,
        assetGroupId: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/images/create" \
     -d '{"model": "nano-banana-pro", "text_prompt": "…"}'
```

**JavaScript**
``` javascript
const model = "nano-banana-pro";
const text_prompt = "text prompt";
const apiUrl = `https://api.useapi.net/v1/runwayml/images/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  model,
  text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
model = "nano-banana-pro"
text_prompt = "text prompt"
apiUrl = f"https://api.useapi.net/v1/runwayml/images/create"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "model": f"{model}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-lipsync-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-lipsync-create
## Create Lip Sync Video
<small>August 8, 2024 (March 21, 2025)</small>

---

Runway [AI Tools » Audio tools » Lip Sync Video](https://app.runwayml.com/video-tools/ai-tools/subtitles).  

Please be aware that Runway's moderation system analyzes your voice text (parameter `voice_text`) and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.  

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/lipsync/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "image_assetId": "Optional assetId of image asset",
    "video_assetId": "Optional assetId of video asset",
    "audio_assetId": "Optional assetId of audio asset",
    "voiceId": "Optional voiceId from lipsync/voices endpoint",
    "voice_text": "Optional lipsync text",
    "model_id": "Optional voice model",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `image_assetId` is optional. Specify the image assetId you want to be present in the first frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `video_assetId` is optional. Specify the video assetId you want to be present in the first frame. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `audio_assetId` is optional. Specify an audio assetId you want to lip sync with provided above image or video. Use [GET /assets/?mediaType=audio](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of audio assets. To upload a new audio asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). 

- `voiceId` is optional. Specify AI voiceId used read `voice_text` to lip sync with provided above image or video. Use [GET lipsync/voices](/docs/api-runwayml-v1/get-runwayml-lipsync-voices) to see the list of voices. 

- `voice_text` is optional. Specify text to lip sync with provided above image or video.

 - `model_id` is optional. Specify [AI voice model](https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them).  
  Supported values: `eleven_multilingual_v1` (default) and `eleven_multilingual_v2` (28+ languages).

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by image/video assetId account will be used.  
  Valid range: 1…10.  
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.  

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "lipsync",
    "options": {
        "name": "<name>",
        "exploreMode": true,
        "paid_user_watermark_override": false,
        "video": "<video url>",
        "video_asset_id": "<video asset uuid>",
        "audio": "<audio ulr>"
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "code": 200,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new [lipsync/create](#create-lip-sync-video) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
    name: string,
    exploreMode: boolean,
    paid_user_watermark_override: boolean,
    image: string,
    image_asset_id: string,
    video: string,
    video_asset_id: string,
    audio: string,
    audio_asset_id: string,
    gen_audio_options: {
      name: string,
      text: string,
      voice_id: string,
      model_id: string
    }
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },  
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/lipsync/create" \
     -d '{"image_assetId": "…", "audio_assetId": "…"}'
```

**JavaScript**
``` javascript
const image_assetId = "assetId of image asset";      
const audio_assetId = "assetId of audio asset";      
const apiUrl = `https://api.useapi.net/v1/runwayml/lipsync/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  image_assetId, audio_assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
image_assetId = "assetId of image asset"      
audio_assetId = "assetId of audio asset"      
apiUrl = f"https://api.useapi.net/v1/runwayml/lipsync/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "image_assetId": f"{image_assetId}",
    "audio_assetId": f"{audio_assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-super_slow_motion ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-super_slow_motion
## Super-Slow Motion
<small>November 8, 2024 (March 21, 2025)</small>

---

Super-Slow Motion uses the power of AI to generate and add new frames to your clips for a crisper, cleaner slow-motion effect on any video of your choosing. It automatically generate new frames to convert your low-frame rate footage into a smooth slow motion video.

Runway [AI Tools » Video tools » Super-Slow Motion](https://app.runwayml.com/video-tools/ai-tools/slow-motion).  

Official [Super-Slow Motion guide](https://help.runwayml.com/hc/en-us/articles/19190044700563-Super-Slow-Motion).

This endpoint offers **free** & **unlimited** Super-Slow Motion generations. It is available to users with **free** accounts without any limitations. You can run as many parallel jobs as you want. Additionally, this endpoint can be used to export your `mp4` videos to Apple's [ProRes 4444](https://support.apple.com/en-us/102207) format.

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/super_slow_motion**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "assetId": "Required assetId of video asset",
    "speed": 0.5,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5,
}
```
- `assetId` is **required**. Specify the video assetId. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. Use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) to upload new video asset.

- `speed` **required**. Specify how much you want to slow down the original video.  
  Valid range from `0.1` (ten times slower) to `1` (original speed).  

- `duration` is optional video duration in seconds, required if assetId does not contain duration information.   
  **NOTE** You can set the duration to 1000 if you do not know the actual value. The Runway API will be able to determine the actual value.

- `width` is optional video width in pixels, required if assetId does not contain width information or if you want to upscale or donwscale original video. Please note that this endpoint does not actually perform upscaling. While you will get a higher resolution output, it is more akin to digital zoom rather than actual upscaling.

- `height` is optional video height in pixels, required if assetId does not contain height information or if you want to upscale or donwscale original video. Please note that this endpoint does not actually perform upscaling. While you will get a higher resolution output, it is more akin to digital zoom rather than actual upscaling.
  
- `format` is optional. Specify desired output format.  
  Valid values: `mp4` (default), `prores` 

- `name` is optional. Specify desired output file name.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.  
  Maximum length 1024 characters.  

- `maxJobs` is optional, if not provided value for referenced by video assetId account will be used.  
  Valid range: 1…10.  
  **NOTE** There's no limit to how many parallel jobs this endpoint can execute, but we still recommend keeping it to a maximum of 10 jobs.

##### Responses 

**200**
**200 OK** 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-super_slow_motion#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
  "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
  "id": "<uuid>",
  "name": "<name>",
  "image": null,
  "createdAt": "2024-08-01T01:02:03.456Z",
  "updatedAt": "2024-08-01T01:02:03.456Z",
  "taskType": "bake_stream",
  "options": {
      "name": "<name>",
      "ignoreAudioStreamFailure": true,
      "videoStreamDescription": {
          "model_name": "rife",
          "command_name": "slow_motion",
          "inputs": {
              "video": "<video asset url>",
              "factor": 2
          },
          "output_width": 768,
          "output_height": 1280
      },
      "videoStart": 0,
      "videoEnd": 20,
      "formatOptions": {
          "format": "mp4"
      },
      "audioStreamDescription": {
          "model_name": "raw_audio",
          "command_name": "time_stretch",
          "inputs": {
              "audio": "<video asset url>",
              "factor": 2
          }
      },
      "audioStart": 0,
      "audioEnd": 20
  },  
  "status": "PENDING",
  "error": null,
  "progressText": null,
  "progressRatio": null,
  "estimatedTimeToStartSeconds": 0,
  "artifacts": [],
  "sharedAsset": null,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "<your optional reference id>",
  "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

* API query is full and can not accept new super_slow_motion requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.
  
```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: any,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
    name: string,
    ignoreAudioStreamFailure: boolean,
    videoStreamDescription: {
        model_name: 'rife',
        command_name: 'slow_motion',
        inputs: {
            video: string,
            factor: number
        },
        output_width: number,
        output_height: number
    },
    videoStart: number,
    videoEnd: number,
    formatOptions: {
        format: string,
        profile?: string
    },
    audioStreamDescription: {
        model_name: 'raw_audio',
        command_name: 'time_stretch',
        inputs: {
            audio: string,
            factor: number
        }
    },
    audioStart: number,
    audioEnd: number
  },
  status: string,
  progressText: any,
  progressRatio: any,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/super_slow_motion" \
     -d '{"assetId": "…", "speed": 0.5 }'
```

**JavaScript**
``` javascript
const assetId = "assetId of video asset";      
const speed = 0.5;      
const apiUrl = `https://api.useapi.net/v1/runwayml/super_slow_motion`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  assetId, speed
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
assetId = "assetId of video asset"  
speed = 0.5    
apiUrl = f"https://api.useapi.net/v1/runwayml/super_slow_motion" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "assetId": f"{assetId}", "speed": speed
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create
## Videos
<small>March 5, 2026 (May 14, 2026)</small>

---

Unified video generation endpoint supporting multiple AI models: [Seedance 2.0](https://seed.bytedance.com/) `seedance-2`, [HappyHorse 1.0](https://fal.ai/happyhorse-1.0) `happyhorse-1.0`, [Kling O3 4K](https://klingai.com/) `kling-o3-4k`, [Kling O3 Pro](https://klingai.com/) `kling-o3-pro`, [Kling O3 Standard](https://klingai.com/) `kling-o3-standard`, [Kling 3.0 Pro](https://klingai.com/) `kling-3.0-pro`, [Kling 3.0 Standard](https://klingai.com/) `kling-3.0-standard`, [Kling 3.0 Motion Control](https://klingai.com/) `kling-3.0-motion-control`, [Kling 2.6 Pro](https://klingai.com/) `kling-2.6-pro`, [Kling 2.6 I2V](https://klingai.com/) `kling-2.6-i2v`, [Wan 2.6 Flash](https://wan.video/) `wan-2.6-flash`, [Wan 2.2 Animate](https://github.com/Wan-Video/Wan2.2) `wan-2.2-animate`, [Veo 3.1](https://deepmind.google/models/veo/) `veo-3.1`, [Sora 2](https://openai.com/index/sora/) `sora-2`, [Sora 2 Pro](https://openai.com/index/sora/) `sora-2-pro`, [Gen-4.5](https://runwayml.com) `gen4.5`, [Gen-4](https://runwayml.com) `gen4`, and [Gen-4 Turbo](https://runwayml.com) `gen4-turbo`.

Each model has different capabilities, duration options, aspect ratios, resolution options, and reference image support.

Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can set `exploreMode` to `true` to generate videos without using credits. Explore mode generations are queued at lower priority and may take significantly longer. Not all models support `exploreMode` — see [model comparison](#model-comparison-gen-45--gen-4) for details. Generation takes ~10 minutes on average. Up to two generations can usually run in parallel per account. Gen-4 Turbo and Veo 3.1 are notably faster (~1–2 min).

##### Model Comparison: Seedance

Seedance 2.0 on Runway supports real-people faces and generally applies lighter content moderation than the [Dreamina](/docs/api-dreamina-v1) version of the same model.

| Feature | Seedance 2.0 |
|---------|:------------:|
| Duration | 4–15s |
| aspect_ratio | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 |
| Resolution | 480p (default), 720p, 1080p |
| Reference images (multi-ref mode) | 0–11 |
| Reference videos (multi-ref mode) | 0–3 |
| Combined references (multi-ref mode) | up to 11 total (images + videos), max 3 of which may be videos |
| Reference video — max duration | ≤ 15 seconds |
| Reference video — max resolution | ≤ 720p (longest side ≤ 1280 px) |
| Keyframe mode | `startFrameAssetId` (required), `endFrameAssetId` (optional, requires `startFrameAssetId`) |
| Keyframe ↔ multi-ref | mutually exclusive in a single request |
| Prompt asset references | `@IMG_1`..`@IMG_11` (images), `@VID_1`..`@VID_3` (videos) |
| text_prompt | optional, 3500 chars |
| audio | on (default) |
| endFrame | yes (dedicated `endFrameAssetId` field) |
| exploreMode | yes |
| Typical generation time (exploreMode) | ~10 min total (queue ~7–9 min + render ~1.5–4 min) |

##### Model Comparison: HappyHorse

| Feature | HappyHorse 1.0 |
|---------|:--------------:|
| Duration | 3–15s |
| aspect_ratio | 16:9, 9:16, 1:1, 4:3, 3:4 |
| Resolution | 720p (default), 1080p |
| Reference images | 0 (T2V) or **1** (I2V — first frame) — `imageAssetId1` only |
| text_prompt | optional, 2500 chars |
| exploreMode | yes |
| Typical generation time (exploreMode) | ~10 min total at 720p (queue ~8 min + render ~1.5 min); up to ~22 min at 1080p/15s |

##### Model Comparison: Kling

| Feature | Kling 3.0 Pro | Kling 3.0 Standard | Kling 2.6 Pro | Kling 2.6 I2V |
|---------|:------------:|:------------------:|:-------------:|:-------------:|
| Duration | 5s, 10s, 15s | 5s, 10s, 15s | 5s, 10s | 5s, 10s |
| aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 | 16:9, 9:16 | — |
| Resolution (T2V) | auto | auto | auto | — |
| Reference images | 0–2 | 0–2 | 0–1 | **1** (required) |
| text_prompt | optional, 2500 chars | optional, 2500 chars | **required**, 2500 chars | **required**, 2500 chars |
| audio | on (default) | on (default) | on (default) | on (default) |
| endFrame | yes | yes | — | — |
| multishot | 2–5 shots | 2–5 shots | — | — |
| exploreMode | yes | yes | yes | yes |

##### Model Comparison: Kling O3

Kling O3 is an omni video model with three workflows per tier — **Frames**, **Multishot**, and **Edit Video**. The three tiers (`kling-o3-4k`, `kling-o3-pro`, `kling-o3-standard`) differ only in output resolution and credit cost; `kling-o3-4k` does not support Edit Video.

- **Frames** — text-to-video and/or up to 7 reference images. A `startFrameAssetId` (first frame) may be combined with reference images; `endFrameAssetId` requires `startFrameAssetId` and **cannot** be combined with reference images.
- **Multishot** — 2–6 shots via `multishot_prompt_N` / `multishot_duration_N` (each shot 3–12 s, total ≤ 15 s). Reference images from `imageAssetId1`..`imageAssetId7` are bound to a shot by referencing them as `@IMG_N` in that shot's prompt.
- **Edit Video** (`kling-o3-pro` / `kling-o3-standard` only) — transform an existing video: `videoAssetId` (source **≤ 10 s**) plus up to 4 reference images. The output duration tracks the source video length.

| Feature | Kling O3 4K | Kling O3 Pro | Kling O3 Standard |
|---------|:-----------:|:------------:|:-----------------:|
| Duration (Frames) | 5s, 10s, 15s | 5s, 10s, 15s | 5s, 10s, 15s |
| aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 |
| Resolution (derived from aspect_ratio) | 3840×2160 / 2160×3840 / 2880×2880 | 1920×1080 / 1080×1920 / 1440×1440 | 1280×720 / 720×1280 / 960×960 |
| Reference images | 0–7 | 0–7 | 0–7 |
| text_prompt | optional, 2500 chars | optional, 2500 chars | optional, 2500 chars |
| audio | on (default) | on (default) | on (default) |
| Keyframes | `startFrameAssetId` + optional `endFrameAssetId` | `startFrameAssetId` + optional `endFrameAssetId` | `startFrameAssetId` + optional `endFrameAssetId` |
| multishot | 2–6 shots (per-shot refs) | 2–6 shots (per-shot refs) | 2–6 shots (per-shot refs) |
| Edit Video | — | yes (`videoAssetId` ≤ 10 s + ≤ 4 refs) | yes (`videoAssetId` ≤ 10 s + ≤ 4 refs) |
| exploreMode | yes | yes | yes |
| Typical generation time (exploreMode) | ~11 min total (queue ~8 min + render ~3 min) | ~11 min total (queue ~8 min + render ~3 min) | ~8 min total (queue ~7 min + render ~1 min) |

##### Model Comparison: Kling Motion Control

Character animation via motion transfer. The character image (`imageAssetId1`) is animated to mimic the gestures and motion of the performance video (`videoAssetId`). Output dimensions inherit from the character image; output duration inherits from the performance video.

| Feature | Kling 3.0 Motion Control |
|---------|:------------------------:|
| Reference image (`imageAssetId1`) | **1** (required) — character to be animated |
| Reference video (`videoAssetId`) | **1** (required) — performance / motion source, **3 ≤ duration ≤ 30 s** |
| Resolution | 720p (default, std mode), 1080p (pro mode) |
| Duration | inherited from reference video — `duration` not accepted |
| aspect_ratio | inherited from character image — `aspect_ratio` not accepted |
| `characterOrientation` | `image` (default) or `video` |
| `audio` | on (default) — keeps the original audio from the reference video; set `false` for silent output |
| text_prompt | optional, 2500 chars (e.g. "Motion description") |
| exploreMode | yes |
| Typical generation time (exploreMode) | ~18 min total (queue ~10 min + render ~8 min) |

##### Model Comparison: Wan

| Feature | Wan 2.6 Flash | Wan 2.2 Animate |
|---------|:-------------:|:---------------:|
| Duration | 5s, 10s, 15s | auto |
| aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1, 4:3, 3:4 |
| Resolution | 720p, 1080p | — |
| Reference images | **1** (required) | **1** (required) |
| Reference video | — | **1** (required) |
| text_prompt | **required**, 1500 chars | — |
| audio | on (default) | — |
| exploreMode | yes | yes |

##### Model Comparison: Veo / Sora

| Feature | Veo 3.1 | Sora 2 | Sora 2 Pro |
|---------|:-------:|:------:|:----------:|
| Duration | 4s, 6s, 8s | 4s, 8s, 12s | 4s, 8s, 12s |
| aspect_ratio | 16:9, 9:16 | 16:9, 9:16 | 16:9, 9:16 |
| Resolution | 720p, 1080p | — | 720p, 1080p |
| Reference images | 0–2 | 0–1 | 0–1 |
| text_prompt | optional, 5000 chars | optional, 1000 chars | optional, 1000 chars |
| audio | on (default) | always on | always on |
| endFrame | yes | — | — |
| exploreMode | **no** | yes | yes |

##### Model Comparison: Gen-4.5 / Gen-4

| Feature | Gen-4.5 | Gen-4 | Gen-4 Turbo |
|---------|:-------:|:-----:|:-----------:|
| Duration | 2–10s | 5s, 10s | 5s, 10s |
| aspect_ratio (T2V) | 16:9 | all | all |
| aspect_ratio (I2V) | all | all | all |
| Resolution | — | 720p | 720p |
| Reference images | 0–1 | **1** (required) | **1** (required) |
| text_prompt | optional, 5000 chars | **required**, 1000 chars | **required**, 1000 chars |
| seed | auto | auto | auto |
| audio | on (default) | — | — |
| exploreMode | yes | yes | yes |

Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.

The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.
> **https://api.useapi.net/v1/runwayml/videos/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "model": "gen4.5",
    "email": "Optional Runway API account email",
    "text_prompt": "A cinematic aerial shot of a coastal city at golden hour",
    "duration": 5,
    "aspect_ratio": "16:9",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```
- `model` is **required**.
  Supported values: `seedance-2`, `happyhorse-1.0`, `kling-o3-4k`, `kling-o3-pro`, `kling-o3-standard`, `kling-3.0-pro`, `kling-3.0-standard`, `kling-3.0-motion-control`, `kling-2.6-pro`, `kling-2.6-i2v`, `wan-2.6-flash`, `wan-2.2-animate`, `veo-3.1`, `sora-2`, `sora-2-pro`, `gen4.5`, `gen4`, `gen4-turbo`.
  See [model comparison](#model-comparison-gen-45--gen-4) for details.

- `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts).

- `text_prompt` describes your video in detail.
  **Required** for `gen4`, `gen4-turbo`, `kling-2.6-pro`, `kling-2.6-i2v`, and `wan-2.6-flash`. Not supported for `wan-2.2-animate`. Optional for all other models.
  Maximum length varies by model (1000–5000 characters; 3500 for `seedance-2`; 2500 for `kling-3.0-motion-control`, `happyhorse-1.0`, and the `kling-o3-*` models).
  For `seedance-2`, prompts may reference uploaded assets by slot using `@IMG_1`..`@IMG_11` and `@VID_1`..`@VID_3`.
  For the `kling-o3-*` models, prompts may reference uploaded assets by slot using `@IMG_1`..`@IMG_7`.

- `duration` is optional. Default is the first supported value for the model.
  - Seedance 2.0: 4–15
  - HappyHorse 1.0: 3–15
  - Kling O3 4K/Pro/Standard: `5`, `10`, `15` (Frames). For multishot, total duration is the sum of the per-shot durations. For Edit Video, duration is derived from the source video and `duration` is ignored.
  - Kling 3.0 Pro/Standard: `5`, `10`, `15`
  - Kling 3.0 Motion Control: not supported (output duration inherits from the reference video)
  - Kling 2.6 Pro, Kling 2.6 I2V: `5`, `10`
  - Wan 2.6 Flash: `5`, `10`, `15`
  - Wan 2.2 Animate: not supported (auto)
  - Veo 3.1: `4`, `6`, `8`
  - Sora 2, Sora 2 Pro: `4`, `8`, `12`
  - Gen-4.5: 2–10 (continuous range)
  - Gen-4, Gen-4 Turbo: `5`, `10`

- `aspect_ratio` is optional. Default varies by model. Available values depend on model — see [model comparison](#model-comparison-gen-45--gen-4).

- `resolution` is optional. Available resolutions depend on model.
  - Seedance 2.0: `480p` (default), `720p`, `1080p`
  - HappyHorse 1.0: `720p` (default), `1080p`
  - Kling 3.0 Motion Control: `720p` (default, "std" mode), `1080p` ("pro" mode)
  - Wan 2.6 Flash: `720p` (default), `1080p`
  - Veo 3.1: `720p` (default), `1080p`
  - Sora 2 Pro: `720p` (default), `1080p`
  - Gen-4, Gen-4 Turbo: `720p`
  - Kling O3 4K/Pro/Standard: not supported — the output resolution is derived from the model tier and `aspect_ratio` (see [Kling O3 model comparison](#model-comparison-kling-o3)).
  - All other models: not supported (resolution auto-selected)

- `audio` is optional. Default `true`. Set to `false` to disable audio generation.
  Supported by: Seedance 2.0, Kling O3 4K/Pro/Standard, Kling 3.0 Pro/Standard, Kling 3.0 Motion Control, Kling 2.6 Pro, Kling 2.6 I2V, Wan 2.6 Flash, Veo 3.1, Gen-4.5.
  For `kling-3.0-motion-control`, `audio` controls whether the original audio of the reference video (`videoAssetId`) is preserved in the output.
  For the `kling-o3-*` models in Edit Video mode, `audio` controls whether the original sound of the source video (`videoAssetId`) is preserved in the output.

- `seed` is optional. Only supported by Gen-4.5, Gen-4, and Gen-4 Turbo (auto-generated if not provided).
  Valid range 1–4294967294.

- `imageAssetId1`, `imageAssetId2` ... `imageAssetId11` are optional. Specify the assetIds of reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets).
  Maximum number of reference images depends on model — see [model comparison](#model-comparison-gen-45--gen-4).
  - `imageAssetId1`: start frame image
  - `imageAssetId2`: end frame image (only for models supporting `endFrame`: Gen-4.5, Kling 3.0 Pro/Standard, Veo 3.1)
  - `imageAssetId3` ... `imageAssetId11`: additional reference image slots, used only by `seedance-2` in multi-reference mode.
  - For the `kling-o3-*` models, `imageAssetId1`..`imageAssetId7` are reference image slots (0–7 images). In Edit Video mode at most 4 reference images are accepted. The end frame for Kling O3 is supplied via `endFrameAssetId` (not `imageAssetId2`).

- `videoAssetId`, `videoAssetId2`, `videoAssetId3` are optional. Specify the assetIds of reference videos. Use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) to upload a video asset.
  - `videoAssetId`: the single reference video for `wan-2.2-animate` (**required** for that model) and for `kling-3.0-motion-control` (**required** as the performance/motion source). Also the source video for `kling-o3-pro` / `kling-o3-standard` Edit Video mode.
  - `videoAssetId2`, `videoAssetId3`: additional video-reference slots used only by `seedance-2` in multi-reference mode.
  - For `seedance-2`, each reference video must be **≤ 15 seconds** long and **≤ 720p** (longest side ≤ 1280 px).
  - For `kling-3.0-motion-control`, the reference video must be **between 3 and 30 seconds**.
  - For `kling-o3-pro` / `kling-o3-standard` Edit Video, the source video must be **≤ 10 seconds**. `kling-o3-4k` does not support Edit Video.

- `startFrameAssetId`, `endFrameAssetId` are optional. Dedicated keyframe fields for `seedance-2` and the `kling-o3-*` models.
  - `startFrameAssetId`: first-frame image (tagged `first_frame` on the wire).
  - `endFrameAssetId`: last-frame image (tagged `end_frame`). Requires `startFrameAssetId` — cannot be supplied alone.
  - For `seedance-2`, keyframe mode is **mutually exclusive** with multi-reference mode (`imageAssetIdN` / `videoAssetIdN`). Using both in the same request returns 400.
  - For the `kling-o3-*` models, `startFrameAssetId` **may** be combined with reference images (`imageAssetId1`..`imageAssetId7`), but `endFrameAssetId` **cannot** — supplying `endFrameAssetId` together with any reference image returns 400.

- `characterOrientation` is optional. Used only by `kling-3.0-motion-control`.
  Supported values: `image` (default), `video`. Controls whether the character's orientation in the output is anchored to the character image or to the performance video.

- `multishot_prompt_N` and `multishot_duration_N` are optional. Multi-shot parameters for creating multi-scene videos. Supported by Kling 3.0 Pro/Standard and the `kling-o3-*` models.
  Each shot requires both a prompt and a duration. Shot duration range: 3–12 seconds. Total duration across all shots must not exceed 15 seconds. Prompt max length: 512 characters per shot. Shots must be numbered contiguously starting from 1.
  - Kling 3.0 Pro/Standard: `multishot_prompt_1`..`multishot_prompt_5` / `multishot_duration_1`..`multishot_duration_5` — minimum 2 shots, maximum 5 shots.
  - Kling O3 4K/Pro/Standard: `multishot_prompt_1`..`multishot_prompt_6` / `multishot_duration_1`..`multishot_duration_6` — minimum 2 shots, maximum 6 shots.
  For the `kling-o3-*` models, reference images supplied via `imageAssetId1`..`imageAssetId7` are bound to a specific shot by referencing them as `@IMG_N` in that shot's prompt — e.g. `@IMG_1` in `multishot_prompt_2` binds `imageAssetId1` to shot 2. The same image may be referenced from multiple shots; an image not referenced by any shot is used as a global reference. An optional first frame for the whole sequence can be supplied via `startFrameAssetId`.

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.
  **Not supported** by `veo-3.1` — will return 400 if set to `true`.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not provided value for referenced by image assetId account will be used.
  Valid range: 1–10.
  Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.

##### Responses

**200**
**200 OK**

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-videos-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "task": {
        "id": "<uuid>",
        "name": "gen4.5 <your text prompt>",
        "image": null,
        "createdAt": "2026-03-05T10:00:00.000Z",
        "updatedAt": "2026-03-05T10:00:00.100Z",
        "taskType": "gen4.5",
        "options": {
            "name": "gen4.5 <your text prompt>",
            "text_prompt": "<your text prompt>",
            "seconds": 5,
            "seed": 12345,
            "watermark": false,
            "route": "t2v",
            "width": 1280,
            "height": 720,
            "assetGroupId": "<uuid>",
            "creationSource": "tool-mode",
            "exploreMode": true,
            "recordingEnabled": true
        },
        "status": "PENDING",
        "error": null,
        "progressText": null,
        "progressRatio": "0",
        "estimatedTimeToStartSeconds": 0,
        "artifacts": [],
        "sharedAsset": null,
        "sourceAssetId": null,
        "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
        "code": 200
    }
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

When `exploreMode` is `true` and another explore mode job is still running, the new job will not start until the current one completes. Since explore mode generations can take significantly longer, you may need to wait before retrying.

There are two possible cases for API response 429:

* API query is full and can not accept new [videos/create](#videos) requests. Size of query defined by [`maxJobs` optional parameter](#request-body).

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

* The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.

```json
{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  taskId: string,
  id: string,
  name: string,
  image: string,
  createdAt: string,
  updatedAt: string,
  taskType: string,
  options: {
        name: string,
        text_prompt: string,
        seconds: number,
        seed: number,
        watermark: boolean,
        route: string,
        width: number,
        height: number,
        exploreMode: boolean,
        assetGroupId: string,
        creationSource: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  error: {
    errorMessage: string,
    reason: string,
    message: string,
    moderation_category: string,
    tally_asimov: boolean
  },
  code: number,
  replyUrl: string,
  replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/videos/create" \
     -d '{"model": "gen4.5", "text_prompt": "A cinematic aerial shot of a coastal city at golden hour", "duration": 5}'
```

**JavaScript**
``` javascript
const model = "gen4.5";
const text_prompt = "A cinematic aerial shot of a coastal city at golden hour";
const duration = 5;
const apiUrl = `https://api.useapi.net/v1/runwayml/videos/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  model,
  text_prompt,
  duration
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
model = "gen4.5"
text_prompt = "A cinematic aerial shot of a coastal city at golden hour"
duration = 5
apiUrl = f"https://api.useapi.net/v1/runwayml/videos/create"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "model": f"{model}",
    "text_prompt": f"{text_prompt}",
    "duration": duration
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-upscale ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-upscale
## Upscale a video to 4K with Topaz AI
<small>May 15, 2026</small>

---

Upscale a video to 4K using Topaz AI. Output preserves the source aspect ratio and bumps the longer dimension up to 4K class (e.g. a 1280×720 source → 4096×2304, a 1080×1920 source → 2160×3840).

The input is a `videoAssetId`. Two common ways to obtain one:

* **Upscale a video you generated** — pass the `assetId` from any video task: [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) outputs (Kling, Sora, Veo, Wan, Seedance, HappyHorse, Gen-4.x), [gen4-video](/docs/api-runwayml-v1/post-runwayml-gen4-video), or any other Runway video task. Look it up later via [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets).
* **Upscale an uploaded video** — upload your own file via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) and use the returned `assetId`.

##### Constraints

| Constraint | Value |
|------------|-------|
| Max source duration | 40 seconds |
| Source media type | `video` |
| Output | 4K (source aspect ratio preserved) |
| Model | Topaz AI (only option) |
| Billing | 2 credits/second, or free with `exploreMode` on Runway Unlimited plan |
> **https://api.useapi.net/v1/runwayml/videos/upscale**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
    "videoAssetId": "Required assetId of any video asset to upscale",
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}
```

- `videoAssetId` is **required**. The video asset to upscale. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to list video assets, or pass through any `assetId` returned by [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create), [gen4-video](/docs/api-runwayml-v1/post-runwayml-gen4-video), [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets), etc. The account that owns the asset is charged for the upscale — no `email` parameter is needed.

- `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.
  Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response.

- `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result.
  Maximum length 1024 characters.

- `maxJobs` is optional, if not provided the value configured for the account owning the video asset will be used. Valid range: 1…10. See [Setup Runway](/docs/start-here/setup-runwayml) for details on per-account concurrency.

##### Responses

**200**
**200 OK**

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The upscaled video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`.

If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-videos-upscale#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "Upscaled <source video name>",
    "image": null,
    "createdAt": "2026-05-15T20:10:08.838Z",
    "updatedAt": "2026-05-15T20:10:08.838Z",
    "taskType": "harrods",
    "options": {
        "name": "Upscaled <source video name>",
        "parent_asset_group_id": "<uuid>",
        "creationSource": "apps",
        "creationSourceAppId": "upscale-video",
        "asset_id": "<source video uuid>",
        "exploreMode": true,
        "recordingEnabled": true
    },
    "status": "THROTTLED",
    "error": null,
    "progressText": null,
    "progressRatio": "0",
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

On completion, polling [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) returns the artifact with the 4K dimensions and a signed download URL:

```json
{
    "status": "SUCCEEDED",
    "progressRatio": "1",
    "artifacts": [
        {
            "id": "<uuid>",
            "assetId": "user:user_id-runwayml:account_email-asset:<uuid>",
            "filename": "<source name> 4K.mp4",
            "url": "https://dnznrvs05pmza.cloudfront.net/<uuid>.mp4?_jwt=...",
            "fileSize": "14173798",
            "metadata": {
                "frameRate": 50,
                "duration": 8,
                "dimensions": [4096, 2304],
                "size": { "width": 4096, "height": 2304 }
            }
        }
    ]
}
```

**400**
**400 Bad Request**

Returned when `videoAssetId` is missing or malformed, the referenced asset is not a video, or the source video exceeds the 40-second maximum:

```json
{
  "error": "videoAssetId duration (52.30s) exceeds maximum 40s for video upscale",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

**412**
**412 Insufficient credits**

You do not have enough credits to run this task. Set `exploreMode: true` if you have a Runway Unlimited plan.

```json
{
    "error": "You do not have enough credits to run this task."
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

```json
{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
    id: string
    taskId: string
    name: string
    image: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        asset_id: string
        creationSource: 'apps'
        creationSourceAppId: 'upscale-video'
        parent_asset_group_id: string
        exploreMode: boolean
        recordingEnabled: boolean
    }
    status: string
    error: {
      errorMessage: string
      reason: string
      message: string
      moderation_category: string
      tally_asimov: boolean
    }
    progressText: string
    progressRatio: number
    estimatedTimeToStartSeconds: number
    artifacts: {
        id: string
        assetId: string
        filename: string
        url: string
        fileSize: string
        previewUrls: string[]
        metadata: {
            frameRate: number
            duration: number
            dimensions: [number, number]
            size: { width: number, height: number }
        }
    }[]
    sharedAsset: any
    sourceAssetId: any
    code: number
    replyUrl: string
    replyRef: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/videos/upscale" \
     -d '{"videoAssetId": "…", "exploreMode": true }'
```

**JavaScript**
``` javascript
const videoAssetId = "assetId of video asset";
const apiUrl = `https://api.useapi.net/v1/runwayml/videos/upscale`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  videoAssetId,
  exploreMode: true
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoAssetId = "assetId of video asset"
apiUrl = f"https://api.useapi.net/v1/runwayml/videos/upscale"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "videoAssetId": f"{videoAssetId}",
    "exploreMode": True
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/start-here/setup-tempolor ===
Document URL: https://useapi.net/docs/start-here/setup-tempolor
# <img style="height:1.2em;vertical-align: middle;" src="/assets/images/tempolor.png"> Setup TemPolor
<small>May  15, 2025</small>

## Table of contents
<small>Approximately 5 minutes to complete setup steps.</small>  

---
> This is the setup guide for [TemPolor API](/docs/api-tempolor-v1). An active [TemPolor](https://www.tempolor.com) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work.

[TemPolor](https://www.tempolor.com), an AI-powered, royalty-free **music generation** service that creates high-quality soundtracks from text prompts, custom lyrics, MIDI, and supports voice cloning. TemPolor offers extensive customization for instrumental tracks, including chords and BPM. Supports export in mp3, wav, and stems, and it can generate stems from users' audio files. Up to 10 tracks can be generated concurrently, with **unlimited** generations available on the [Ultra](https://www.tempolor.com/pricing) plan.

## Create TemPolor account 

Create a [TemPolor](https://www.tempolor.com) account if you don't have one already.

## Locate your TemPolor `requestParams`

Open a Chromium-compatible browser (e.g. [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/en-us/edge), or [Opera](https://www.opera.com/)) and navigate to your TemPolor account profile page [https://www.tempolor.com/account/profile](https://www.tempolor.com/account/profile) <span style="color: red;">`1`</span>.  

![](/assets/images/tempolor_setup_1.png)

Refresh the page <span style="color: red;">`2`</span>.

Once the page is fully loaded, ensure that you're logged in and current page is [https://www.tempolor.com/account/profile](https://www.tempolor.com/account/profile).  

Open [Developer Tools](https://developer.chrome.com/docs/devtools) by right-clicking on the page and selecting "Inspect Element" or via [keyboard shortcuts](https://developer.chrome.com/docs/devtools/shortcuts): Mac `Command+Option+I` or Windows `F12` or `Control+Shift+I`.

Select Developer Tools » Network <span style="color: red;">`3`</span>:  
* Make sure that `All` or `Fetch/XHR` is selected <span style="color: red;">`4`</span>.  
* Type `/getWebSelfUserInfo` in the filter box <span style="color: red;">`5`</span> and hit Enter.  
* You should see a single HTTP call entry as shown below <span style="color: red;">`6`</span> and click on that entry.  
* Select the "Payload" tab <span style="color: red;">`7`</span>.  
* Locate and select the "Request Payload" header <span style="color: red;">`8`</span>.  
* Right-click on the `requestParams` and copy its content <span style="color: red;">`9`</span>.   
  This is your `requestParams`.

<details markdown="block">

<summary>As an example above, the <b>requestParams</b> (JSON)</summary>
  
```json
{
  "requestParams": {
    "sv": "alpha/beta/release",
    "ver_code": 20000,
    "lang": "french",
    "la": "fr-FR",
    "di": "e23c9f7db8ced478b8574923817c2b6a",
    "pf": "100",
    "mi": "Windows",
    "biz": 378,
    "utdid": "e23c9f7db8ced478b8574923817c2b6a",
    "ts": 1849982225671,
    "service_ticket": "hUUCp7MeIAXpXKo9AOP5zPlJLqVZh81C2MWlZdTuqoGbNqzlgQNjBwtxdYnJPRA52Wn=",
    "ucid": "100349856",
    "user_id": "100349856",
    "member_level": 0,
    "is_visitor": 0,
    "vip_type": 20,
    "app_id": "material",
    "app": "web",
    "ve": "2.0.0",
    "entry": "web_main",
    "fr": "web",
    "ip": "88.222.199.44",
    "business_type": "material",
    "la_multi": "fr",
    "b_ts": "1849512371543",
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.39 (KHTML, like Gecko) Chrome/122.1.0.0 Safari/537.39 OPR/123.0.0.0",
    "web_terminal": "web_pc"
  }
}
```

</details>

## Verify and add account

Use the form below to verify your credentials and add your TemPolor account.

Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-tempolor-v1/post-tempolor-accounts) directly.

<script>
  async function apiTestAccountTempolor(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-Tempolor-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let body;
      try {
        body = JSON.parse(document.getElementById(`post-accounts-Tempolor-requestParams`)?.value);
      } catch (e) {
        body = {};
      }
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/tempolor/accounts`, 'post-accounts-Tempolor', data);
  }
</script>

<form id="post-accounts-Tempolor" onsubmit="apiTestAccountTempolor(document.getElementById('post-accounts-Tempolor-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Tempolor-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Tempolor-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Tempolor-requestParams"><span>requestParams (JSON)</span>
        <textarea id="post-accounts-Tempolor-requestParams" class="input-element" required aria-required="true" spellcheck="false" rows="5" style="resize:vertical; min-height:5em; max-height:20em;font-size: smaller;" oninput="this.rows = Math.min(10, Math.max(5, this.value.split('\n').length));"></textarea>    </label>
      <label for="post-accounts-Tempolor-action"><span>action</span>
        <select id="post-accounts-Tempolor-action" class="input-element">
          <option value="verify">Verify — test credentials only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Tempolor-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-Tempolor-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-tempolor-v1 ===
Document URL: https://useapi.net/docs/api-tempolor-v1

# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/tempolor.png"> TemPolor API v1 

<small>May 15, 2025 (March 21, 2026)</small>

This is an [experimental](/docs/legal) API for [TemPolor](https://www.tempolor.com), an AI-powered, royalty-free **music generation** service that creates high-quality soundtracks from text prompts, custom lyrics, MIDI, and supports voice cloning. TemPolor offers extensive customization for instrumental tracks, including chords and BPM. Supports export in mp3, wav, and stems, and it can generate stems from users' audio files. Up to 10 tracks can be generated concurrently, with **unlimited** generations available on the [Ultra](https://www.tempolor.com/pricing) plan.

**Song models:**
- `v4.5+` (default) — 16+ languages including English, Chinese, Japanese, Korean, Spanish, French, Russian, Hindi, Arabic and more. Max 5 min
- `v3.5` — English, Chinese, Japanese, Korean, Spanish, French. Max 4.5 min
- `v3` — English, Chinese, Japanese. Max 2 min

**Instrumental models:**
- `i3.5 beta` (default) — Richer arrangements, max 4.5 min
- `i3` — Superior music structure, max 2 min

Using the [Ultra $30/m](https://www.tempolor.com/pricing) TemPolor web subscription used by this API, you can generate an **unlimited** number of songs. Compare this to the official API pricing, which starts at [$300/m](https://platform.tempolor.com/pricing) for 10,000 songs per month.

[Setup TemPolor](/docs/start-here/setup-tempolor)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(March 21, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-tempolor-v1.txt) <small>Feed this to your LLM to build integrations</small>

Articles:
* [TemPolor v4.5+ Multilingual Song](/blog/260321)
* [TemPolor API Samples](/blog/250515)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/TemPolorAPI/"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/TemPolorAPI</a>

=== URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-accounts-user_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-accounts-user_id
## Delete TemPolor API account
<small>May 15, 2025</small>

---

This endpoint deletes a TemPolor API account configuration.

[Setup TemPolor](/docs/start-here/setup-tempolor)
> **https://api.useapi.net/v1/tempolor/accounts/`user_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content**  

Account configuration was successfully deleted.

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Account configuration not found.

##### Examples

**Curl**
``` bash
curl -X DELETE https://api.useapi.net/v1/tempolor/accounts/<user_id> \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/tempolor/accounts/${user_id}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  }
});
console.log("response", response);
```

**Python**
``` python
import requests
token = "API token"
user_id = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/tempolor/accounts/{user_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response)
```

=== URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-scheduler-job_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-scheduler-job_id
## Cancel a running job
<small>May 15, 2025</small>

---

This endpoint cancels a running API job from being tracked by the scheduler. The job will still be executed by TemPolor, but the API will no longer track its progress.
> **https://api.useapi.net/v1/tempolor/scheduler/`job_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `job_id` is **required**. The job to cancel, as returned from [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song), [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental), or [GET scheduler](/docs/api-tempolor-v1/get-tempolor-scheduler).

##### Responses 

**204**
**204 No Content**  

Job was successfully cancelled.

**400**
**400 Bad Request**

The job_id format is invalid.

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

The specified job was not found or could not be cancelled.

```json
{
  "error": "Unable to locate running job_id",
  "code": 404
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE "https://api.useapi.net/v1/tempolor/scheduler/<job_id>" \
  -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const job_id = "user:12345-tempolor:user_id-job:abcdef123456789";
const apiUrl = `https://api.useapi.net/v1/tempolor/scheduler/${job_id}`;

const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});

if (response.status === 204) {
  console.log("Job cancelled successfully");
} else {
  const errorData = await response.json();
  console.error("Failed to cancel job:", errorData);
}
```

**Python**
``` python
import requests

token = "API token"
job_id = "user:12345-tempolor:user_id-job:abcdef123456789"
api_url = f"https://api.useapi.net/v1/tempolor/scheduler/{job_id}"

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.delete(api_url, headers=headers)

if response.status_code == 204:
    print("Job cancelled successfully")
else:
    try:
        error_data = response.json()
        print(f"Failed to cancel job: {error_data}")
    except:
        print(f"Failed to cancel job: {response.status_code}")
```

=== URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-cloned-voices-clonedVoiceItemId ===
Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-cloned-voices-clonedVoiceItemId
## Delete a cloned voice
<small>May 15, 2025</small>

---

This endpoint deletes a previously created cloned voice.
> **https://api.useapi.net/v1/tempolor/music/cloned-voices/`clonedVoiceItemId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path Parameters

- `clonedVoiceItemId` is **required**. The cloned voice ID returned from a previous [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) request.

##### Responses 

**200**
**200 OK**  

```json
{
  "result": true
}
```

**400**
**400 Bad Request**

```json
{
  "error": "clonedVoiceItemId has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "No record found for user:12345-tempolor:user_id-voice:abcdef123456789",
  "code": 404
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/cloned-voices/user:12345-tempolor:user_id-voice:abcdef123456789
```

**JavaScript**
``` javascript
const clonedVoiceItemId = "user:12345-tempolor:user_id-voice:abcdef123456789";
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices/${clonedVoiceItemId}`;

const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log("Delete result:", result.result);
```

**Python**
``` python
import requests

cloned_voice_item_id = "user:12345-tempolor:user_id-voice:abcdef123456789"
token = "API token"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices/{cloned_voice_item_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.delete(apiUrl, headers=headers)
result = response.json()
print(f"Delete result: {result.get('result')}")
```

=== URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-job_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-job_id
## Delete a music generation
<small>May 15, 2025</small>

---

This endpoint deletes a previously generated music item.
> **https://api.useapi.net/v1/tempolor/music/`job_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request.

##### Responses 

**200**
**200 OK**  

```json
{
  "result": true
}
```

**400**
**400 Bad Request**

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789
```

**JavaScript**
``` javascript
const job_id = "user:12345-tempolor:user_id-job:abcdef123456789";
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`;

const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log("Delete result:", result.result);
```

**Python**
``` python
import requests

job_id = "user:12345-tempolor:user_id-job:abcdef123456789"
token = "API token"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.delete(apiUrl, headers=headers)
result = response.json()
print(f"Delete result: {result.get('result')}")
```

=== URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-midi-midiItemId ===
Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-midi-midiItemId
## Delete a MIDI file
<small>May 15, 2025</small>

---

This endpoint deletes a previously uploaded MIDI file.
> **https://api.useapi.net/v1/tempolor/music/midi/`midiItemId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path Parameters

- `midiItemId` is **required**. The MIDI file ID returned from a previous [POST music/midi](/docs/api-tempolor-v1/post-tempolor-music-midi) request.

##### Responses 

**200**
**200 OK**  

```json
{
  "result": true
}
```

**400**
**400 Bad Request**

```json
{
  "error": "midiItemId has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "No record found for user:12345-tempolor:user_id-midi:abcdef123456789",
  "code": 404
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/midi/user:12345-tempolor:user_id-midi:abcdef123456789
```

**JavaScript**
``` javascript
const midiItemId = "user:12345-tempolor:user_id-midi:abcdef123456789";
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/${midiItemId}`;

const response = await fetch(apiUrl, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log("Delete result:", result.result);
```

**Python**
``` python
import requests

midi_item_id = "user:12345-tempolor:user_id-midi:abcdef123456789"
token = "API token"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/{midi_item_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.delete(apiUrl, headers=headers)
result = response.json()
print(f"Delete result: {result.get('result')}")
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts-user_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts-user_id
## Retrieve TemPolor API account configuration for `user_id`
<small>May 15, 2025</small>

---

This endpoint retrieves the details of a specific TemPolor account.

[Setup TemPolor](/docs/start-here/setup-tempolor)
> **https://api.useapi.net/v1/tempolor/accounts/`user_id`**

The `user_id` value should correspond to an account configured previously via a [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  

```json
{
  "user_id": "user_id1",
  "updated": 1715791234567,
  "updatedUTC": "2025-05-15T14:30:34.567Z",
  "maxJobs": 10,
  "requestParams": {}
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts).

##### Model 

```typescript
{   // TypeScript
  user_id: string
  updated: number // timestamp in milliseconds
  updatedUTC: string // ISO date string
  maxJobs: number
  requestParams: {}
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/tempolor/accounts/<user_id> \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/tempolor/accounts/${user_id}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
user_id = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/tempolor/accounts/{user_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts
## Get List of Accounts
<small>May 15, 2025</small>

---

This endpoint retrieves the complete list of configured API accounts for TemPolor.

[Setup TemPolor](/docs/start-here/setup-tempolor)
> **https://api.useapi.net/v1/tempolor/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  

```json
{
  "user_id1": {
    "user_id": "user_id1",
    "updated": 1715791234567,
    "updatedUTC": "2025-05-15T14:30:34.567Z",
    "maxJobs": 10,
    "requestParams": {}
  },
  "user_id2": {
    "user_id": "user_id2",
    "updated": 1715791234567,
    "updatedUTC": "2025-05-15T14:30:34.567Z",
    "maxJobs": 20,
    "requestParams": {} 
  }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Returned when no accounts are configured.

##### Model 

```typescript
{   // TypeScript
  [user_id: string]: {
    user_id: string
    updated: number // timestamp in milliseconds
    updatedUTC: string // ISO date string
    maxJobs: number
    requestParams: {}
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X GET https://api.useapi.net/v1/tempolor/accounts
```

**JavaScript**
``` javascript
const apiUrl = `https://api.useapi.net/v1/tempolor/accounts`; 
const api_token = "API token";  
const data = { 
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = f"https://api.useapi.net/v1/tempolor/accounts" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-artist-voices ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-artist-voices
## List artist voices
<small>May 15, 2025</small>

---

This endpoint retrieves a list of predefined artist voices that you can use for music generation without uploading your own voice samples. These artist voices can be used with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the `artistVoiceItemId` parameter.
> **https://api.useapi.net/v1/tempolor/music/artist-voices/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `cursor` is optional. Pagination cursor for fetching additional pages of results.

##### Responses 

**200**
**200 OK**  

```json
{
  "records": [
    {
      "ucid": "9999999",
      "bizType": "ai_voice_cloned",
      "itemId": "voice_12345",
      "name": "Deep Male Voice",
      "resourceUrl": "https://example.com/vocals/deep-male-sample.mp3",
      "coverUrl": "https://example.com/voice-covers/deep-male.jpg",
      "vocalUrl": "https://example.com/vocals/deep-male-sample.mp3",
      "weight": 100,
      "isAddRel": false,
      "relSource": "",
      "labels": ["male", "deep", "dramatic"]
    },
    {
      "ucid": "9999999",
      "bizType": "ai_voice_cloned",
      "itemId": "voice_67890",
      "name": "Soprano Female Voice",
      "resourceUrl": "https://example.com/vocals/soprano-female-sample.mp3",
      "coverUrl": "https://example.com/voice-covers/soprano-female.jpg",
      "vocalUrl": "https://example.com/vocals/soprano-female-sample.mp3",
      "weight": 90,
      "isAddRel": false,
      "relSource": "",
      "labels": ["female", "soprano", "clear"]
    }
  ],
  "hasNext": false,
  "cursor": "",
  "sysTime": 1716565425000
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    records: {
        ucid: string
        bizType: string
        itemId: string
        name: string
        resourceUrl: string
        coverUrl: string
        vocalUrl: string
        weight: number
        isAddRel: boolean
        relSource: string
        labels: string[]
    }[]
    hasNext: boolean
    cursor: string
    sysTime: number
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
# List all artist voices
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=user_id

# Paginate through results using cursor
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=user_id&cursor=next_page_cursor_token"
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "user_id"; 
const cursor = ""; // for pagination

// Build the URL with query parameters
let apiUrl = `https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=${user_id}`;
if (cursor) apiUrl += `&cursor=${cursor}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log(`Found ${result.records?.length || 0} artist voices`);

// Example of fetching all pages
async function fetchAllArtistVoices(userId) {
  let allRecords = [];
  let nextCursor = "";
  let hasMore = true;
  
  while (hasMore) {
    let url = `https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=${userId}`;
    if (nextCursor) url += `&cursor=${nextCursor}`;
    
    const response = await fetch(url, {
      method: "GET",
      headers: { "Authorization": `Bearer ${token}` }
    });
    
    const data = await response.json();
    
    if (data.records && data.records.length > 0) {
      allRecords = [...allRecords, ...data.records];
    }
    
    hasMore = data.hasNext;
    nextCursor = data.cursor;
    
    // Break if no more pages or no cursor
    if (!hasMore || !nextCursor) break;
  }
  
  return allRecords;
}
```

**Python**
``` python
import requests

token = "API token"
user_id = "user_id"
cursor = ""  # for pagination

# Build the URL with query parameters
apiUrl = f"https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id={user_id}"
if cursor:
    apiUrl += f"&cursor={cursor}"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
result = response.json()
print(f"Found {len(result.get('records', []))} artist voices")

# Example of fetching all pages
def fetch_all_artist_voices(user_id):
    all_records = []
    next_cursor = ""
    has_more = True
    
    while has_more:
        url = f"https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id={user_id}"
        if next_cursor:
            url += f"&cursor={next_cursor}"
        
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data.get('records'):
            all_records.extend(data.get('records'))
        
        has_more = data.get('hasNext', False)
        next_cursor = data.get('cursor', "")
        
        # Break if no more pages or no cursor
        if not has_more or not next_cursor:
            break
    
    return all_records
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-cloned-voices ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-cloned-voices
## List cloned voices
<small>May 15, 2025</small>

---

This endpoint retrieves a list of cloned voices that you've previously created using [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices). These cloned voices can be used in music generation with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song).
> **https://api.useapi.net/v1/tempolor/music/cloned-voices/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `cursor` is optional. Pagination cursor for fetching additional pages of results.

##### Responses 

**200**
**200 OK**  

```json
{
  "records": [
    {
      "isAddRel": false,
      "relSource": "",
      "ucid": "user_id",
      "bizType": "user",
      "operatorType": "gen",
      "itemId": "abcdef123456789",
      "rootItemId": "abcdef123456789",
      "parentItemId": "abcdef123456789",
      "name": "My Custom Voice",
      "resourceUrl": "voice_cloned/audio/abcdef123456789.mp3",
      "coverUrl": "",
      "readStatus": 0,
      "status": 30,
      "vocalUrl": "https://example.com/cloned-voice/abcdef123456789.mp3",
      "createTime": 1716565425000,
      "updateTime": 1716565700000,
      "labels": [],
      "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789"
    },
    {
      "isAddRel": false,
      "relSource": "",
      "ucid": "user_id",
      "bizType": "user",
      "operatorType": "gen",
      "itemId": "fedcba987654321",
      "rootItemId": "fedcba987654321",
      "parentItemId": "fedcba987654321",
      "name": "Second Voice Sample",
      "resourceUrl": "voice_cloned/audio/fedcba987654321.mp3",
      "coverUrl": "",
      "readStatus": 0,
      "status": 30,
      "vocalUrl": "https://example.com/cloned-voice/fedcba987654321.mp3",
      "createTime": 1716475425000,
      "updateTime": 1716475700000,
      "labels": [],
      "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:fedcba987654321"
    }
  ],
  "hasNext": false,
  "cursor": ""
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    records: {
        isAddRel: boolean
        relSource: string
        ucid: string
        bizType: string
        operatorType: string
        itemId: string
        rootItemId: string
        parentItemId: string
        name: string
        resourceUrl: string
        coverUrl: string
        readStatus: number
        status: number
        vocalUrl: string
        createTime: number
        updateTime: number
        labels: string[]
        clonedVoiceItemId: string
    }[]
    hasNext: boolean
    cursor: string
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
# List all cloned voices
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=user_id

# Paginate through results using cursor
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=user_id&cursor=next_page_cursor_token"
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "user_id"; 
const cursor = ""; // for pagination

// Build the URL with query parameters
let apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=${user_id}`;
if (cursor) apiUrl += `&cursor=${cursor}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log(`Found ${result.records?.length || 0} cloned voices`);

// Example of fetching all pages
async function fetchAllClonedVoices(userId) {
  let allRecords = [];
  let nextCursor = "";
  let hasMore = true;
  
  while (hasMore) {
    let url = `https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=${userId}`;
    if (nextCursor) url += `&cursor=${nextCursor}`;
    
    const response = await fetch(url, {
      method: "GET",
      headers: { "Authorization": `Bearer ${token}` }
    });
    
    const data = await response.json();
    
    if (data.records && data.records.length > 0) {
      allRecords = [...allRecords, ...data.records];
    }
    
    hasMore = data.hasNext;
    nextCursor = data.cursor;
    
    // Break if no more pages or no cursor
    if (!hasMore || !nextCursor) break;
  }
  
  return allRecords;
}
```

**Python**
``` python
import requests

token = "API token"
user_id = "user_id"
cursor = ""  # for pagination

# Build the URL with query parameters
apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id={user_id}"
if cursor:
    apiUrl += f"&cursor={cursor}"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
result = response.json()
print(f"Found {len(result.get('records', []))} cloned voices")

# Example of fetching all pages
def fetch_all_cloned_voices(user_id):
    all_records = []
    next_cursor = ""
    has_more = True
    
    while has_more:
        url = f"https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id={user_id}"
        if next_cursor:
            url += f"&cursor={next_cursor}"
        
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data.get('records'):
            all_records.extend(data.get('records'))
        
        has_more = data.get('hasNext', False)
        next_cursor = data.get('cursor', "")
        
        # Break if no more pages or no cursor
        if not has_more or not next_cursor:
            break
    
    return all_records
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-download-job_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-download-job_id
## Download generated music
<small>May 15, 2025</small>

---

This endpoint retrieves a download URL for a completed music generation job. The `job_id` must be from a successfully completed generation job that can be verified with [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id).
> **https://api.useapi.net/v1/tempolor/music/download/`job_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request.

##### Query Parameters

- `file_format` is optional. Specifies the format of the generated music to download.  
  Supported values:
  * `mp3` - MP3 format (default)
  * `wav` - WAV format (higher quality)
  * `stems` - ZIP archive containing separated stems (vocals, instruments, etc.)

##### Responses 

**200**
**200 OK**  

```json
{
  "url": "https://ugc-cdn.api.instabeat.ai/ai_material/ai_material/mp3/abcdef123456789.mp3?auth_key=1747536678-0-0-9c67b3d5f8a2c41e0d7f6eab3f82fb45",
  "remainSeconds": 0
}
```

The download URL expires after `remainSeconds` seconds.

**400**
**400 Bad Request**

```json
{
  "error": "Generation is not completed yet (0)",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    url: string
    remainSeconds: number
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
# Download in MP3 format (default)
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789

# Download in WAV format (higher quality)
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789?file_format=wav"

# Download stems (separated vocal, instruments, etc.)
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789?file_format=stems"
```

**JavaScript**
``` javascript
const job_id = "user:12345-tempolor:user_id-job:abcdef123456789";
const token = "API token";
const file_format = "mp3"; // or "wav" or "stems"
const apiUrl = `https://api.useapi.net/v1/tempolor/music/download/${job_id}?file_format=${file_format}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log("Download URL:", result.url);

// Example of downloading the file
async function downloadFile(downloadUrl, fileName) {
  const fileResponse = await fetch(downloadUrl);
  const blob = await fileResponse.blob();
  
  // For browser environments
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.style.display = 'none';
  a.href = url;
  a.download = fileName;
  document.body.appendChild(a);
  a.click();
  window.URL.revokeObjectURL(url);
  
  // For Node.js environments
  // const fs = require('fs');
  // const buffer = Buffer.from(await blob.arrayBuffer());
  // fs.writeFileSync(fileName, buffer);
}

// If the request was successful, download the file
if (result.url) {
  const fileName = `tempolor-music-${Date.now()}.${file_format === 'stems' ? 'zip' : file_format}`;
  await downloadFile(result.url, fileName);
}
```

**Python**
``` python
import requests
import os

job_id = "user:12345-tempolor:user_id-job:abcdef123456789"
token = "API token"
file_format = "mp3"  # or "wav" or "stems"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/download/{job_id}?file_format={file_format}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
result = response.json()
print("Download URL:", result.get("url"))

# Example of downloading the file
def download_file(download_url, file_name):
    file_response = requests.get(download_url)
    with open(file_name, 'wb') as f:
        f.write(file_response.content)
    print(f"File downloaded as {file_name}")

# If the request was successful, download the file
if result.get("url"):
    if file_format == "stems":
        file_name = f"tempolor-music-{job_id.split(':')[-1]}.zip"
    else:
        file_name = f"tempolor-music-{job_id.split(':')[-1]}.{file_format}"
    download_file(result.get("url"), file_name)
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-job_id ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-job_id
## Check music generation status and results
<small>May 15, 2025</small>

---

This endpoint checks the status of a previously submitted music generation job. The `job_id` is returned from [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental).
> **https://api.useapi.net/v1/tempolor/music/`job_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request.

##### Status Values

The response includes a `status` field with the following possible values:

| status | status_name | status_final | Description                              |
|--------|-------------|--------------|------------------------------------------|
| 0      | GENERATING  | False        | The music is still being generated       |
| 10     | FAILED      | True         | The music generation has failed          |
| 30     | COMPLETED   | True         | The music has been successfully generated|

When the status is COMPLETED, you can download the music using the [GET music/download/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) endpoint.

##### Responses 

**200**
**200 OK**  

<details markdown="block">

<summary>Example Response</summary>

```json
{
  "bizType": "ai_material_music",
  "childType": "lyric_to_material",
  "matChildType": "lyric_to_material",
  "sourceType": "sm_user_gen",
  "itemId": "abcdef123456789",
  "job_id": "user:12345-tempolor:user_id-job:abcdef123456789",
  "genItemId": "abcdef123456789",
  "userId": "user_id",
  "titleEn": "Epic Orchestral",
  "cover": "https://example.com/cover.png",
  "mp3OssId": "ai_material/ai_material/mp3/abcdef123456789.mp3",
  "wavOssId": "ai_material/ai_material/wav/abcdef123456789.wav",
  "ossWatermarkMp3": "",
  "officialPlaylistSong": false,
  "status": 30,
  "status_name": "COMPLETED",
  "status_final": true,
  "progress": 100,
  "downloadTotal": 0,
  "likeTotal": 0,
  "collectTotal": 0,
  "musicMaterial": {
    "style": "Orchestral",
    "chord": "",
    "mood": "",
    "inst": "",
    "instInfo": "",
    "scene": "",
    "otherInfo": "A cinematic orchestral piece with dramatic string sections",
    "otherInfoCn": "",
    "key": "F:minor",
    "bpm": 130,
    "dur": 180,
    "seed": 1234567890,
    "waveformUrl": "https://example.com/waveform.json"
  },
  "readStatus": false,
  "downloadStatus": false,
  "createTime": 1716565425000,
  "updateTime": 1716565700000,
  "materialQualityScore": 0,
  "ltmMaterialExtendDto": {
    "lyricsPrompt": "Sample lyrics here",
    "description": "A cinematic orchestral piece with dramatic string sections",
    "ltmVocalModel": false,
    "ltmMidiModel": false,
    "genItemId": "abcdef123456789",
    "prompt": "A cinematic orchestral piece with dramatic string sections",
    "genMode": 0,
    "model": "v1-dit-obleck-stereo-zh-en-270-wf",
    "modelShowName": "v3.5"
  },
  "editType": "gen",
  "operatorType": "gen",
  "rootItemId": "abcdef123456789",
  "parentItemId": "abcdef123456789",
  "canExtend": true,
  "canEditLyrics": true,
  "canFixVocals": true,
  "canReplaced": false
}
```

</details>

**400**
**400 Bad Request**

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    bizType: string
    childType: string
    matChildType: string
    sourceType: string
    itemId: string
    job_id: string
    genItemId: string
    userId: string
    titleEn: string
    cover: string
    mp3OssId: string
    wavOssId: string
    ossWatermarkMp3: string
    status: number
    status_name: string // "GENERATING", "FAILED", "COMPLETED"
    status_final: boolean
    progress: number
    downloadTotal: number
    likeTotal: number
    collectTotal: number
    musicMaterial: {
        style: string
        chord: string
        mood: string
        inst: string
        instInfo: string
        scene: string
        otherInfo: string
        otherInfoCn: string
        key: string
        bpm: number
        dur: number
        seed: number
    }
    createTime: number
    updateTime: number
    ltmMaterialExtendDto: {
        lyricsPrompt: string
        description: string
        prompt: string
        genMode: number
        model: string
    }
    editType: string
    operatorType: string
    canExtend: boolean
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789
```

**JavaScript**
``` javascript
const job_id = "user:12345-tempolor:user_id-job:abcdef123456789";
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log("response", {response, result});

// Polling example - check status every 10 seconds until completed or failed
async function pollJobStatus(job_id) {
  const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`;
  
  while (true) {
    const response = await fetch(apiUrl, {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${token}`
      }
    });
    
    const result = await response.json();
    console.log(`Job status: ${result.status_name}, Progress: ${result.progress}%`);
    
    if (result.status_final) {
      console.log(`Music generation ${result.status_name.toLowerCase()}`);
      return result;
    }
    
    // Wait 10 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}
```

**Python**
``` python
import requests
import time

job_id = "user:12345-tempolor:user_id-job:abcdef123456789"
token = "API token"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
print(response.status_code, response.json())

# Polling example - check status every 10 seconds until completed or failed
def poll_job_status(job_id):
    apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}"
    
    while True:
        response = requests.get(apiUrl, headers=headers)
        result = response.json()
        print(f"Job status: {result.get('status_name')}, Progress: {result.get('progress')}%")
        
        if result.get('status_final'):
            print(f"Music generation {result.get('status_name').lower()}")
            return result
        
        # Wait 10 seconds before checking again
        time.sleep(10)
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-midi ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-midi
## List MIDI files
<small>May 15, 2025</small>

---

This endpoint retrieves a list of MIDI files that you've previously uploaded using [POST music/midi](/docs/api-tempolor-v1/post-tempolor-music-midi). These MIDI files can be used as templates for music generation with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song).
> **https://api.useapi.net/v1/tempolor/music/midi/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `cursor` is optional. Pagination cursor for fetching additional pages of results.

##### Responses 

**200**
**200 OK**  

```json
{
  "records": [
    {
      "opType": "upload",
      "ucid": "user_id",
      "midiItemId": "user:12345-tempolor:user_id-midi:abcdef123456789",
      "name": "Piano Composition",
      "midiUrl": "https://ugc-cdn.api.instabeat.ai/midi/file/abcdef123456789.mid"
    },
    {
      "opType": "upload",
      "ucid": "user_id",
      "midiItemId": "user:12345-tempolor:user_id-midi:fedcba987654321",
      "name": "Guitar Progression",
      "midiUrl": "https://ugc-cdn.api.instabeat.ai/midi/file/fedcba987654321.mid"
    }
  ],
  "hasNext": false,
  "cursor": ""
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    records: {
        opType: string
        ucid: string
        midiItemId: string
        name: string
        midiUrl: string
        midiType?: string
        midiValue?: string
    }[]
    hasNext: boolean
    cursor: string
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
# List all MIDI files
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/midi/?user_id=user_id

# Paginate through results using cursor
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/midi/?user_id=user_id&cursor=next_page_cursor_token"
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "user_id"; 
const cursor = ""; // for pagination

// Build the URL with query parameters
let apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/?user_id=${user_id}`;
if (cursor) apiUrl += `&cursor=${cursor}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log(`Found ${result.records?.length || 0} MIDI files`);

// Example of fetching all pages
async function fetchAllMidiFiles(userId) {
  let allRecords = [];
  let nextCursor = "";
  let hasMore = true;
  
  while (hasMore) {
    let url = `https://api.useapi.net/v1/tempolor/music/midi/?user_id=${userId}`;
    if (nextCursor) url += `&cursor=${nextCursor}`;
    
    const response = await fetch(url, {
      method: "GET",
      headers: { "Authorization": `Bearer ${token}` }
    });
    
    const data = await response.json();
    
    if (data.records && data.records.length > 0) {
      allRecords = [...allRecords, ...data.records];
    }
    
    hasMore = data.hasNext;
    nextCursor = data.cursor;
    
    // Break if no more pages or no cursor
    if (!hasMore || !nextCursor) break;
  }
  
  return allRecords;
}
```

**Python**
``` python
import requests

token = "API token"
user_id = "user_id"
cursor = ""  # for pagination

# Build the URL with query parameters
apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/?user_id={user_id}"
if cursor:
    apiUrl += f"&cursor={cursor}"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
result = response.json()
print(f"Found {len(result.get('records', []))} MIDI files")

# Example of fetching all pages
def fetch_all_midi_files(user_id):
    all_records = []
    next_cursor = ""
    has_more = True
    
    while has_more:
        url = f"https://api.useapi.net/v1/tempolor/music/midi/?user_id={user_id}"
        if next_cursor:
            url += f"&cursor={next_cursor}"
        
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data.get('records'):
            all_records.extend(data.get('records'))
        
        has_more = data.get('hasNext', False)
        next_cursor = data.get('cursor', "")
        
        # Break if no more pages or no cursor
        if not has_more or not next_cursor:
            break
    
    return all_records
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music
## List music generation jobs
<small>May 15, 2025</small>

---

This endpoint retrieves a list of previously generated music items. You can filter the results by type and paginate through them using the cursor parameter.
> **https://api.useapi.net/v1/tempolor/music/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `type` is optional. Filter results by the type of music generation.  
  Supported values:
  * `song` - Show music with vocals (default)
  * `instrumental` - Show instrumental music only

- `cursor` is optional. Pagination cursor for fetching additional pages of results.

##### Responses 

**200**
**200 OK**  

<details markdown="block">

<summary>Example Response</summary>

```json
{
  "records": [
    {
      "bizType": "ai_material_music",
      "childType": "lyric_to_material",
      "matChildType": "lyric_to_material",
      "sourceType": "sm_user_gen",
      "itemId": "abcdef123456789",
      "job_id": "user:12345-tempolor:user_id-job:abcdef123456789",
      "genItemId": "abcdef123456789",
      "userId": "user_id",
      "titleEn": "Epic Orchestral",
      "cover": "https://example.com/cover.png",
      "mp3OssId": "ai_material/ai_material/mp3/abcdef123456789.mp3",
      "wavOssId": "ai_material/ai_material/wav/abcdef123456789.wav",
      "ossWatermarkMp3": "",
      "officialPlaylistSong": false,
      "status": 30,
      "status_name": "COMPLETED",
      "status_final": true,
      "progress": 100,
      "downloadTotal": 0,
      "likeTotal": 0,
      "collectTotal": 0,
      "musicMaterial": {
        "style": "Orchestral",
        "chord": "",
        "mood": "",
        "inst": "",
        "instInfo": "",
        "scene": "",
        "otherInfo": "A cinematic orchestral piece with dramatic string sections",
        "otherInfoCn": "",
        "key": "F:minor",
        "bpm": 130,
        "dur": 180,
        "seed": 1234567890,
        "waveformUrl": "https://example.com/waveform.json"
      },
      "readStatus": false,
      "downloadStatus": false,
      "createTime": 1716565425000,
      "updateTime": 1716565700000,
      "materialQualityScore": 0,
      "ltmMaterialExtendDto": {
        "lyricsPrompt": "Sample lyrics here",
        "description": "A cinematic orchestral piece with dramatic string sections",
        "ltmVocalModel": false,
        "ltmMidiModel": false,
        "genItemId": "abcdef123456789",
        "prompt": "A cinematic orchestral piece with dramatic string sections",
        "genMode": 0,
        "model": "v1-dit-obleck-stereo-zh-en-270-wf",
        "modelShowName": "v3.5"
      },
      "editType": "gen",
      "operatorType": "gen",
      "rootItemId": "abcdef123456789",
      "parentItemId": "abcdef123456789",
      "canExtend": true,
      "canEditLyrics": true,
      "canFixVocals": true,
      "canReplaced": false
    }
  ],
  "hasNext": true,
  "cursor": "next_page_cursor_token"
}
```

</details>

**400**
**400 Bad Request**

```json
{
  "error": "Invalid type parameter. Must be 'song' or 'instrumental'",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    records: {
        bizType: string
        childType: string
        matChildType: string
        sourceType: string
        itemId: string
        job_id: string
        genItemId: string
        userId: string
        titleEn: string
        cover: string
        mp3OssId: string
        wavOssId: string
        ossWatermarkMp3: string
        officialPlaylistSong: boolean
        status: number
        status_name: string 
        status_final: boolean
        progress: number
        downloadTotal: number
        likeTotal: number
        collectTotal: number
        musicMaterial: {
            style: string
            chord: string
            mood: string
            inst: string
            instInfo: string
            scene: string
            otherInfo: string
            otherInfoCn: string
            key: string
            bpm: number
            dur: number
            seed: number
            src: string
            ossSrc: string
            waveformOssId: string
            waveformUrl: string
            batchId: string
        }
        readStatus: boolean
        downloadStatus: boolean
        createTime: number
        updateTime: number
        materialQualityScore: number
        ltmMaterialExtendDto: {
            lyricsPrompt: string
            description: string
            ltmVocalModel: boolean
            ltmMidiModel: boolean
            lrcTimestamp: string
            genItemId: string
            prompt: string
            genMode: number
            model: string
            modelShowName: string
            dynamicModel: string
            oriCacheDir: string
        }
        editType: string
        operatorType: string
        rootItemId: string
        parentItemId: string
        canExtend: boolean
        canEditLyrics: boolean
        canFixVocals: boolean
        canReplaced: boolean
    }[]
    hasNext: boolean
    cursor: string
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
# List all song generations (default)
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/?user_id=user_id

# List only instrumental music
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/?user_id=user_id&type=instrumental

# Paginate through results using cursor
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/tempolor/music/?user_id=user_id&cursor=next_page_cursor_token"
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "user_id"; 
const type = "song"; // or "instrumental"
const cursor = ""; // for pagination

// Build the URL with query parameters
let apiUrl = `https://api.useapi.net/v1/tempolor/music/?user_id=${user_id}`;
if (type) apiUrl += `&type=${type}`;
if (cursor) apiUrl += `&cursor=${cursor}`;

const response = await fetch(apiUrl, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
});
const result = await response.json();
console.log(`Found ${result.records?.length || 0} music items`);

// Example of fetching all pages
async function fetchAllMusicItems(userId, type) {
  let allRecords = [];
  let nextCursor = "";
  let hasMore = true;
  
  while (hasMore) {
    let url = `https://api.useapi.net/v1/tempolor/music/?user_id=${userId}`;
    if (type) url += `&type=${type}`;
    if (nextCursor) url += `&cursor=${nextCursor}`;
    
    const response = await fetch(url, {
      method: "GET",
      headers: { "Authorization": `Bearer ${token}` }
    });
    
    const data = await response.json();
    
    if (data.records && data.records.length > 0) {
      allRecords = [...allRecords, ...data.records];
    }
    
    hasMore = data.hasNext;
    nextCursor = data.cursor;
    
    // Break if no more pages or no cursor
    if (!hasMore || !nextCursor) break;
  }
  
  return allRecords;
}
```

**Python**
``` python
import requests

token = "API token"
user_id = "user_id"
type_param = "song"  # or "instrumental"
cursor = ""  # for pagination

# Build the URL with query parameters
apiUrl = f"https://api.useapi.net/v1/tempolor/music/?user_id={user_id}"
if type_param:
    apiUrl += f"&type={type_param}"
if cursor:
    apiUrl += f"&cursor={cursor}"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(apiUrl, headers=headers)
result = response.json()
print(f"Found {len(result.get('records', []))} music items")

# Example of fetching all pages
def fetch_all_music_items(user_id, type_param=None):
    all_records = []
    next_cursor = ""
    has_more = True
    
    while has_more:
        url = f"https://api.useapi.net/v1/tempolor/music/?user_id={user_id}"
        if type_param:
            url += f"&type={type_param}"
        if next_cursor:
            url += f"&cursor={next_cursor}"
        
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data.get('records'):
            all_records.extend(data.get('records'))
        
        has_more = data.get('hasNext', False)
        next_cursor = data.get('cursor', "")
        
        # Break if no more pages or no cursor
        if not has_more or not next_cursor:
            break
    
    return all_records
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler-available ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler-available
## Get available capacity
<small>May 15, 2025</small>

---

Get information about currently executing jobs and available capacity for all configured accounts.
> **https://api.useapi.net/v1/tempolor/scheduler/available**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Responses 

**200**
**200 OK**  

The response contains information about currently executing jobs and available capacity.

```json
{
  "executing": [
    {
      "job_id": "user:12345-tempolor:12345-job:abcdef123456789",
      "started": "2025-05-15T12:34:56.789Z",
      "elapsed": "01:23",
      "replyUrl": "https://example.com/callback",
      "replyRef": "my-reference"
    }
  ],
  "available": [
    {
      "user_id": "12345",
      "maxJobs": 10,
      "executing": 1,
      "available": 9
    },
    {
      "user_id": "67890",
      "maxJobs": 5,
      "executing": 0,
      "available": 5
    }
  ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{
  executing: [ // Currently executing jobs
    {
      job_id: string
      started: string  // ISO timestamp when the job started
      elapsed: string  // Time elapsed since start in MM:SS format
      replyUrl?: string  // Optional callback URL if specified during job creation
      replyRef?: string  // Optional reference if specified during job creation
    }
  ],
  available: [ // Accounts with available capacity
    {
      user_id: string  // Account identifier
      maxJobs: number  // Maximum concurrent jobs allowed for this account
      executing: number  // Number of currently executing jobs
      available: number  // Number of available job slots (maxJobs - executing)
    }
  ]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/tempolor/scheduler/available" \
  -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/tempolor/scheduler/available";

const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`
  }
});

const result = await response.json();
console.log("Scheduler info:", result);

// Find account with most available capacity
if (result.available && result.available.length > 0) {
  const bestAccount = result.available[0]; // Sorted by availability
  console.log(`Best account to use: ${bestAccount.user_id} (${bestAccount.available} slots available)`);
}
```

**Python**
``` python
import requests

token = "API token"
api_url = "https://api.useapi.net/v1/tempolor/scheduler/available"

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(api_url, headers=headers)
result = response.json()
print("Scheduler info:", result)

# Find account with most available capacity
if result.get('available') and len(result['available']) > 0:
    best_account = result['available'][0]  # Sorted by availability
    print(f"Best account to use: {best_account['user_id']} ({best_account['available']} slots available)")
```

=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler
## List scheduled jobs
<small>May 15, 2025</small>

---

Get a list of currently executing music generation jobs.
> **https://api.useapi.net/v1/tempolor/scheduler/**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Responses 

**200**
**200 OK**  

The response contains an array of currently executing music generation jobs.

```json
[
  {
    "job_id": "user:12345-tempolor:user_id-job:abcdef123456789",
    "started": "2025-05-15T12:34:56.789Z",
    "elapsed": "01:23",
    "replyUrl": "https://example.com/callback",
    "replyRef": "my-reference"
  }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
[
  { // TypeScript representation of each job
    job_id: string
    started: string  // ISO timestamp when the job started
    elapsed: string  // Time elapsed since start in MM:SS format
    replyUrl?: string  // Optional callback URL if specified during job creation
    replyRef?: string  // Optional reference if specified during job creation
  }
]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/tempolor/scheduler/" \
  -H "Authorization: Bearer …"
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/tempolor/scheduler/";

const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`
  }
});

const result = await response.json();
console.log("Current jobs:", result);
```

**Python**
``` python
import requests

token = "API token"
api_url = "https://api.useapi.net/v1/tempolor/scheduler/"

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(api_url, headers=headers)
result = response.json()
print("Current jobs:", result)
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts
## Create or update TemPolor API account
<small>May 15, 2025</small>

---

This endpoint configures a TemPolor API account with the provided credentials.

[Setup TemPolor](/docs/start-here/setup-tempolor)
> **https://api.useapi.net/v1/tempolor/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "requestParams": {},
  "maxJobs": 10
}
```

- `requestParams` is **required**, see [Setup TemPolor](/docs/start-here/setup-tempolor) for details on how to obtain it.

- `maxJobs` is optional, the maximum number of concurrent jobs allowed for this account.  
  Default is 10.

##### Responses 

**200**
**200 OK**  

```json
{
  "user_id": "123456789",
  "updated": 1715791234567,
  "updatedUTC": "2025-05-15T14:30:34.567Z",
  "maxJobs": 10,
  "requestParams": {}
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter requestParams is required",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**402**
**402 Payment Required**
```json
{
  "error": "Subscription required",
  "code": 402
}
```

##### Model 

```typescript
{   // TypeScript
  user_id: string
  updated: number // timestamp in milliseconds
  updatedUTC: string // ISO date string
  maxJobs: number
  requestParams: {}
}
```

##### Examples

**Curl**
``` bash
curl -X POST https://api.useapi.net/v1/tempolor/accounts \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -d '{
       "requestParams": {},
       "maxJobs": 10
     }'
```

**JavaScript**
``` javascript
const apiUrl = `https://api.useapi.net/v1/tempolor/accounts`; 
const api_token = "API token";  
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' 
  },
  body: JSON.stringify({
    requestParams: {},
    maxJobs: 10
  })
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
import json

apiUrl = "https://api.useapi.net/v1/tempolor/accounts" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization": f"Bearer {api_token}"
}
payload = {
    "requestParams": {},
    "maxJobs": 10
}
response = requests.post(apiUrl, headers=headers, data=json.dumps(payload))
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices
## Upload voice sample for cloning
<small>May 15, 2025</small>

---

This endpoint uploads an audio sample for voice cloning, which can then be used in the [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) endpoint to generate vocals with your cloned voice.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/tempolor/music/cloned-voices/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: {audio content-type}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:

| Content-Type | File Extension |
| ------------ | -------------- |
| audio/mp4    | m4a            |
| audio/x-m4a  | m4a            |
| audio/mpeg   | mp3            |
| audio/wav    | wav            |
| audio/wave   | wav            |
| audio/flac   | flac           |
| audio/x-flac | flac           |

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `name` is **required**. Specify a name for your cloned voice.

##### Responses 

**200**
**200 OK**  

The cloned voice is immediately available to use in [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the returned `clonedVoiceItemId`.

```json
{
  "result": true,
  "itemId": "abcdef123456789",
  "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789"
}
```

**202**
**202 Accepted**  

The voice cloning process is still in progress. Check back later using [GET music/cloned-voices](/docs/api-tempolor-v1/get-tempolor-music-cloned-voices) to see if the voice is ready.

```json
{
  "itemId": "abcdef123456789",
  "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789",
  "message": "Voice cloning is still processing after 120 seconds. Please check back later."
}
```

**400**
**400 Bad Request**

```json
{
  "error": "Empty file received",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemId: string
    clonedVoiceItemId: string
    message: string
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/tempolor/music/cloned-voices/?name=my-custom-voice&user_id=<user_id>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @/path/to/your/voice-sample.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "Previously configured account"; 
const name = "Your voice name"; 
const apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices/?name=${name}&user_id=${user_id}`; 
let blob;

/* 
    // Example 1: Fetch audio from URL
    const audioUrl = "https://example.com/audio-samples/voice-sample.mp3";
    const responseAudio = await fetch(audioUrl);
    blob = await responseAudio.blob();
*/

/* 
    // Example 2: Load audio from local file (Node.js)
    const fs = require('fs');
    const audioFileName = "./voice-sample.mp3";
    blob = new Blob([fs.readFileSync(audioFileName)]);
*/

/*
    // Example 3: Load from input file html element
    // <input id="audio-file" type="file"> 
    const audioFile = document.getElementById(`audio-file`);
    if (audioFile.files[0])
        blob = audioFile.files[0];
*/

const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "audio/mpeg" // Adjust based on your file type
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
user_id = "Previously configured account"
name = "Your voice name"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices/?name={name}&user_id={user_id}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'  # Adjust based on your file type
}

# # Example 1: Fetch audio from URL
# audio_url = "https://example.com/audio-samples/voice-sample.mp3"
# response_audio = requests.get(audio_url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
audio_file_path = "./voice-sample.mp3"
with open(audio_file_path, 'rb') as audio_file:
    file_content = audio_file.read()

response = requests.post(apiUrl, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental
## Create instrumental music
<small>May 15, 2025</small>

---

This endpoint generates instrumental music based on a text prompt and optional musical parameters.
> **https://api.useapi.net/v1/tempolor/music/instrumental**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "prompt": "A relaxing lo-fi beat with piano and soft drums",
  "tonality": "C:major",
  "bpm": 80,
  "chords": "C F G Am"
}
```

- `user_id` is optional, if not specified, the API will use the account from your request.

- `prompt` is **required**, a text description of the desired instrumental music.  
  Maximum length 2000 characters.

- `model_instrumental` is optional, the model to use for generation.  
  Supported values:
  * `i3` - Superior music structure, max 2 min
  * `i3.5 beta` - Richer arrangements, max 4.5 mins (default)

- `tonality` is optional, the musical key for the composition.  
  Supported values: `A:major`, `A:minor`, `Ab:major`, `Ab:minor`, `B:major`, `B:minor`, `Bb:major`, `Bb:minor`, `C#:major`, `C#:minor`, `C:major`, `C:minor`, `D:major`, `D:minor`, `E:major`, `E:minor`, `Eb:major`, `Eb:minor`, `F#:major`, `F#:minor`, `F:major`, `F:minor`, `G:major`, `G:minor`

- `bpm` is optional, the tempo in beats per minute.  
  Valid range: 50…190.

- `chords` is optional, chord progression for the composition.  
  Maximum length 200 characters.

- `replyUrl` is optional, a callback URL that will be called with generation progress updates.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) response.

- `replyRef` is optional, a reference ID that will be included in the callback requests.  
  Maximum length 1024 characters.

- `maxJobs` is optional; it specifies the maximum number of concurrent jobs for this request. If not provided, the value will be taken from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts).

##### Responses 

**200**
**200 OK**  

Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id).

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with generation progress updates until the generation is complete or fails.

```json
{
  "result": true,
  "itemIds": [
    "abcdef123456789",
    "fedcba987654321"
  ],
  "jobs": [
      "user:12345-tempolor:user_id-job:abcdef123456789",
      "user:12345-tempolor:user_id-job:fedcba987654321",
  ],
  "remainSeconds": 21533,
  "maxGenCountAtOnce": 10,
  "unlimited": false,
  "remainNum": 1534,
  "totalNum": 3000
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter prompt is required",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**402**
**402 Payment Required**
```json
{
  "error": "Subscription required",
  "code": 402
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and cannot accept new instrumental music generation requests. Size of queue defined by the `maxJobs` value from either the request body or the default from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts).
```json
{
  "error": "Account <user_id> is busy executing X jobs",
  "runningJobs": {
    "<user_id>": [
      {
        "user_id": "<user_id>",
        "job_id": "<job_id>",
        "started": 1715791234567,
        "replyUrl": "call back URL here, if provided",
        "replyRef": "reference id here, if provided"
      }
    ]
  },
  "code": 429
}
```
2. The API received an HTTP response status 429 from TemPolor.
```json
{
  "error": "please wait for current Generations to finish or upgrade your plan",
  "code": 429
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemIds: string[]
    jobs: string[]
    remainSeconds: number
    maxGenCountAtOnce: number
    unlimited: boolean
    remainNum: number
    totalNum: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/tempolor/music/instrumental \
     -d '{"prompt": "A relaxing lo-fi beat with piano and soft drums"}'
```

**JavaScript**
``` javascript
const apiUrl = `https://api.useapi.net/v1/tempolor/music/instrumental`; 
const api_token = "API token";
const prompt = "A relaxing lo-fi beat with piano and soft drums";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = f"https://api.useapi.net/v1/tempolor/music/instrumental" 
api_token = "API token"
prompt = "A relaxing lo-fi beat with piano and soft drums"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi
## Upload MIDI file
<small>May 15, 2025</small>

---

This endpoint uploads a MIDI file that can be used as a base for music generation in the [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) endpoint.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/tempolor/music/midi/?...**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/midi or audio/x-midi
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, must be `audio/midi` or `audio/x-midi`.

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `name` is **required**. Specify a name for your MIDI file.

##### Responses 

**200**
**200 OK**  

The MIDI file is immediately available to use in [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the returned `midiItemId`.

```json
{
  "isFirst": false,
  "midiRenderVO": {
    "opType": "upload",
    "ucid": "100198329",
    "midiItemId": "user:12345-tempolor:user_id-midi:abcdef123456789",
    "name": "my background music",
    "midiUrl": "https://..."
  }
}
```

**400**
**400 Bad Request**

```json
{
  "error": "Content-Type must be audio/midi or audio/x-midi",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    isFirst: boolean
    midiRenderVO: {
        opType: string
        ucid: string
        midiItemId: string
        name: string
        midiUrl: string
    }
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/tempolor/music/midi/?name=my-background-music&user_id=<user_id>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/midi" \
  --data-binary @/path/to/your/background-music.mid
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "Previously configured account"; 
const name = "my-background-music"; 
const apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/?name=${name}&user_id=${user_id}`; 
let blob;

/* 
    // Example 1: Fetch MIDI from URL
    const midiUrl = "https://example.com/midi-files/background-music.mid";
    const responseMidi = await fetch(midiUrl);
    blob = await responseMidi.blob();
*/

/* 
    // Example 2: Load MIDI from local file (Node.js)
    const fs = require('fs');
    const midiFileName = "./background-music.mid";
    blob = new Blob([fs.readFileSync(midiFileName)], { type: "audio/midi" });
*/

/*
    // Example 3: Load from input file html element
    // <input id="midi-file" type="file" accept=".mid,.midi"> 
    const midiFile = document.getElementById(`midi-file`);
    if (midiFile.files[0])
        blob = midiFile.files[0];
*/

const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "audio/midi"
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
user_id = "Previously configured account"
name = "my-background-music"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/?name={name}&user_id={user_id}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/midi'
}

# # Example 1: Fetch MIDI from URL
# midi_url = "https://example.com/midi-files/background-music.mid"
# response_midi = requests.get(midi_url)
# file_content = response_midi.content

# # Example 2: Load MIDI from local file
midi_file_path = "./background-music.mid"
with open(midi_file_path, 'rb') as midi_file:
    file_content = midi_file.read()

response = requests.post(apiUrl, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song
## Create music with vocals
<small>May 15, 2025 (March 21, 2026)</small>

---

This endpoint generates a complete song with vocals based on a text prompt and optional parameters.
> **https://api.useapi.net/v1/tempolor/music/song**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "prompt": "A cinematic orchestral piece with dramatic string sections and a powerful crescendo",
  "lyrics": "These are the lyrics for my song\nSecond line of the lyrics",
  "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789",
  "replyUrl": "https://your-callback-url.com",
  "replyRef": "your-reference-id"
}
```

- `user_id` is optional, if not specified, the API will use the account from your request.

- `prompt` is **required**, a text description of the desired song.  
  Maximum length 2000 characters.  

- `lyrics` is optional, custom lyrics for the song. If not provided, lyrics will be auto-generated based on the prompt.  
  Maximum length 3000 characters.  

- `model_song` is optional, the model to use for generation.  
  Supported values:
  * `v3` - Enhanced AI music generation supporting English, Chinese, Japanese, max 2 min
  * `v3.5` - Supporting English, Chinese, Japanese, Korean, Spanish, French, max 4.5 min
  * `v4.5+` - Next-gen proprietary model with 16+ languages (English, Chinese, Japanese, Korean, Spanish, French, Russian, Hindi, Arabic and more), max 5 min (default)

- `artistVoiceItemId` is optional, ID of a predefined artist voice to use for the vocals. Get available voices using [GET artist-voices](/docs/api-tempolor-v1/get-tempolor-music-artist-voices).

- `clonedVoiceItemId` is optional, ID of a previously cloned voice to use for the vocals.
  - To get existing cloned voices, use [GET cloned-voices](/docs/api-tempolor-v1/get-tempolor-music-cloned-voices).
  - To create a new cloned voice, upload an audio sample using [POST cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices).

- `midiItemId` is optional, ID of a previously uploaded MIDI file to base the composition on.
  - To get existing MIDI files, use [GET midi](/docs/api-tempolor-v1/get-tempolor-music-midi).
  - To upload a new MIDI file, use [POST midi](/docs/api-tempolor-v1/post-tempolor-music-midi).

- `replyUrl` is optional, a callback URL that will be called with generation progress updates.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) response.

- `replyRef` is optional, a reference ID that will be included in the callback requests.  
  Maximum length 1024 characters.

- `maxJobs` is optional; it specifies the maximum number of concurrent jobs for this request. If not provided, the value will be taken from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts).
  
**Important notes:**
- You can only use one of `artistVoiceItemId` or `clonedVoiceItemId`, not both.
- If you specify a `midiItemId`, you cannot use `artistVoiceItemId` or `clonedVoiceItemId`.

##### Responses 

**200**
**200 OK**  

Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id).

If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with generation progress updates until the generation is complete or fails.

```json
{
  "result": true,
  "itemIds": [
    "abcdef123456789",
    "fedcba987654321"
  ],
  "jobs": [
      "user:12345-tempolor:user_id-job:abcdef123456789",
      "user:12345-tempolor:user_id-job:fedcba987654321",
  ],
  "remainSeconds": 21533,
  "maxGenCountAtOnce": 10,
  "unlimited": false,
  "remainNum": 1534,
  "totalNum": 3000
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Parameter prompt is required",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**402**
**402 Payment Required**
```json
{
  "error": "Subscription required",
  "code": 402
}
```

**404**
**404 Not Found**
```json
{
  "error": "The source material does not exist.",
  "code": 404
}
```

This error may occur if the specified `artistVoiceItemId`, `clonedVoiceItemId`, or `midiItemId` no longer exists.

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and cannot accept new music generation requests. Size of queue defined by the `maxJobs` value from either the request body or the default from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts).
```json
{
  "error": "Account <user_id> is busy executing X jobs",
  "runningJobs": {
    "<user_id>": [
      {
        "user_id": "<user_id>",
        "job_id": "<job_id>",
        "started": 1715791234567,
        "replyUrl": "call back URL here, if provided",
        "replyRef": "reference id here, if provided"
      }
    ]
  },
  "code": 429
}
```
2. The API received an HTTP response status 429 from TemPolor.
```json
{
  "error": "please wait for current Generations to finish or upgrade your plan",
  "code": 429
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemIds: string[]
    jobs: string[]
    remainSeconds: number
    maxGenCountAtOnce: number
    unlimited: boolean
    remainNum: number
    totalNum: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/tempolor/music/song \
     -d '{"prompt": "A cinematic orchestral piece with dramatic string sections"}'
```

**JavaScript**
``` javascript
const apiUrl = `https://api.useapi.net/v1/tempolor/music/song`; 
const api_token = "API token";
const prompt = "A cinematic orchestral piece with dramatic string sections";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = f"https://api.useapi.net/v1/tempolor/music/song" 
api_token = "API token"
prompt = "A cinematic orchestral piece with dramatic string sections"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-stems-splitter ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-stems-splitter
## Split audio into stems
<small>May 15, 2025</small>

---

Upload an audio file (MP3, WAV, M4A, FLAC) and split it into separate instrument stems (vocals, drums, bass, etc).

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/tempolor/music/stems-splitter/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type | File Extension |
| ------------ | -------------- |
| audio/mpeg   | mp3            |
| audio/wav    | wav            |
| audio/wave   | wav            |
| audio/mp4    | m4a            |
| audio/x-m4a  | m4a            |
| audio/flac   | flac           |
| audio/x-flac | flac           |

##### Query Parameters

- `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

When the response includes `stemsZipUrl`, the processing is complete and you can download the ZIP file containing the separated stems.

```json
{
    "state": 2,
    "title": "audio_file.mp3",
    "stemsZipUrl": "https://example.com/path/to/stems.zip"
}
```

**400**
**400 Bad Request**

The server encountered an error processing your request.

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  state: number
  title: string
  stemsZipUrl: string  // URL to download the zip with separated stems
  audioType: string 
  detail: string[] 
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id=<user_id>" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @/path/to/your/audio-track.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const user_id = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id=${user_id}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const audioUrl = "https://example.com/path/to/audio-track.mp3";
    const responseAudio = await fetch(audioUrl);
    blob = await responseAudio.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const audioFileName = "./audio-track.mp3";
    blob = new Blob([await fsp.readFile(audioFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="audio-file" type="file"> 
    const audioFile = document.getElementById(`audio-file`);
    if (audioFile.files[0])
        blob = audioFile.files[0];
*/

// Upload the audio file for stem splitting
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "audio/mpeg"
  },
  body: blob
});

const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
import time

token = "API token"
user_id = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id={user_id}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# import requests
# audio_url = "https://example.com/path/to/audio-track.mp3"
# response_audio = requests.get(audio_url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
audio_file_path = "./audio-track.mp3"
with open(audio_file_path, 'rb') as audio_file:
    file_content = audio_file.read()

response = requests.post(apiUrl, headers=headers, data=file_content)
result = response.json()
print(response.status_code, result)
```

=== URL: https://useapi.net/docs/api-v2 ===
Document URL: https://useapi.net/docs/api-v2

# <img style="height:2em;vertical-align: middle;" src="/assets/images/midjourney.svg">Midjourney API v2 
<small>December 2023 (December 8, 2025)</small>

This is an [experimental](/docs/legal) API for the [Midjourney Discord Bot](https://discord.com/invite/midjourney) by [Midjourney](https://www.midjourney.com).

Since its initial release in early 2023, our experimental API has provided pure and unrestricted access to the Midjourney Discord Bot, allowing you to utilize its full potential. The **entire** Midjourney Discord Bot functionality, including **video generation**, is supported, as well as retrieval of [seed](https://docs.midjourney.com/docs/seeds), support for [variations mode](https://docs.midjourney.com/docs/variations), [remix mode](https://docs.midjourney.com/docs/remix), and everything else the Midjourney Discord Bot offers. Think of our experimental API as a smart proxy for your Midjourney Discord bot.

Our experimental API uses intelligent logic to prevent potential issues with Discord and Midjourney, such as bans, CAPTCHA challenges, or excessive requests. API comes with an automated [CAPTCHA solver](api-v2/captcha-solver) at no additional cost.

We fully support the ability to use [multiple Midjourney accounts](/docs/api-v2/setup-multiple-midjourney-accounts), complete with automated load balancing.

[Setup Midjourney](/docs/start-here/setup-midjourney)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(January 20, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-v2.txt) <small>Feed this to your LLM to build integrations</small>

[Q&A](/docs/questions-and-answers)

[GitHub repo with code examples](https://github.com/useapi/examples)

Articles:
* [Interact with Midjourney using Discord API • Part I](/docs/articles/discord-api-part-1)
* [Interact with Midjourney using Discord API • Part II](/docs/articles/discord-api-part-2)
* [Discord CDN Proxy](/docs/articles/discord-cdn-proxy)
* [Automating Asset Generation with the Midjourney API • Part I](/docs/articles/asset-generation-part-1)

Examples: 
* [Midjourney Video](/blog/250728)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/midjourney_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/reddit.svg"> r/midjourney_api</a>

=== URL: https://useapi.net/docs/api-v2/captcha-solver ===
Document URL: https://useapi.net/docs/api-v2/captcha-solver
# CAPTCHA Solver
<small>December 8, 2025</small>

---

Our API includes an **automated CAPTCHA solver** at no additional cost with your subscription.

## What Triggers CAPTCHA Challenges

Midjourney Discord bot may present CAPTCHA challenges when it detects unusual activity patterns:

- Too many generations in a short period of time
- Recently created Discord accounts are more likely to be challenged
- Active connections from different geographical locations for the same account

## How It Works

When a CAPTCHA is detected:

1. The generation that triggered the CAPTCHA fails with a `596` error. The Midjourney account is locked and updated with an error message explaining that a CAPTCHA was detected. All subsequent API calls for this account will return `596` until the CAPTCHA solver unlocks the account or you manually resolve it via [POST /account/channel/reset](/docs/api-v2/post-account-midjourney-channel-reset)
2. You receive a notification email immediately
3. The CAPTCHA solver is triggered automatically
4. A second email is sent either:
   - Confirming the solver successfully cleared the CAPTCHA and unlocked the account, or
   - Asking you to solve it manually (rare cases)

The entire process takes 60-90 seconds. Based on our in-house testing, we expect the success rate to be close to 100%.

👉 We strongly recommend setting your Discord account language to **English**. Our CAPTCHA solver is primarily tested with English and may not work as reliably with other languages.

## Important: Preventing Excessive CAPTCHAs

While our CAPTCHA solver will handle challenges automatically, **frequent CAPTCHAs indicate you are pushing the account too hard**. Continued aggressive usage patterns may lead to **permanent account bans** by Discord/Midjourney.

To avoid problems:

### Add More Accounts

If you're hitting CAPTCHAs frequently, consider adding more Midjourney accounts to spread the load. Our API supports [multiple accounts](/docs/api-v2/setup-multiple-midjourney-accounts) with automatic load balancing.

### Handle 596 Errors Gracefully

When you receive a `596` error response, it indicates account issues (often CAPTCHA-related). Consider a 10-15 minute cooloff period before retrying. If you have multiple accounts configured, our load balancer will automatically switch to a different one.

### Recommended Practices

- Spread load across multiple accounts
- Add random delays between generations
- If you run mostly `--relax` generations, execute `--fast` once in a while

## No Additional Cost

The CAPTCHA solver is **included free** with your useapi.net subscription. There are no per-solve charges or hidden fees.

=== URL: https://useapi.net/docs/api-v2/del-account-midjourney-channel ===
Document URL: https://useapi.net/docs/api-v2/del-account-midjourney-channel
## Delete Midjourney account
<small>December 2023</small>

---
> **https://api.useapi.net/v2/account/midjourney/`channel`**

The `channel` value should correspond to an account configured previously via a [POST account/midjourney](/docs/api-v2/post-account-midjourney) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v2/account/midjourney/<channel> 
```

**JavaScript**
``` javascript
const channel = "Previously configured channel id"; 
const apiUrl = `https://api.useapi.net/v2/account/midjourney/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
channel = "Previously configured channel id" 
apiUrl = f"https://api.useapi.net/v2/account/midjourney/{channel}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-account-midjourney-channel ===
Document URL: https://useapi.net/docs/api-v2/get-account-midjourney-channel
## Retrieve Midjourney configuration for `channel` 
<small>December 2023 (May 5, 2025)</small>

---
> **https://api.useapi.net/v2/account/midjourney/`channel`**

The `channel` value should correspond to an account configured previously via a [POST account/midjourney](/docs/api-v2/post-account-midjourney) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
  "channel": "Discord channel id",
  "discord": "Discord token",
  "maxJobs": 1-15
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string, 
  channel: string,
  maxJobs: number,
  pendingModMessage: string
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/account/midjourney/<channel> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const channel = "Previously configured channel id"; 
const apiUrl = `https://api.useapi.net/v2/account/midjourney/${channel}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
channel = "Previously configured channel id"
apiUrl = f"https://api.useapi.net/v2/account/midjourney/{channel}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-account-midjourney ===
Document URL: https://useapi.net/docs/api-v2/get-account-midjourney
## Retrieve Midjourney accounts information
<small>December 2023 (May 5, 2025)</small>

---

For your convenience, you can specify your Midjourney configuration values under your account so that you no longer need to provide them with every API call. If you specify multiple Midjourney accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Discord / Midjourney.

This endpoint retrieves the complete list of configured accounts for Midjourney.
> **https://api.useapi.net/v2/account/midjourney**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "Discord channel A": {
        "channel": "Discord channel A",
        "discord": "Discord token A",
        "maxJobs": 1-15
    },
    "Discord channel B": {
        "channel": "Discord channel B",
        "discord": "Discord token B",
        "maxJobs": 1-15
    },
    "Discord channel N": {
        "channel": "Discord channel N",
        "discord": "Discord token N",
        "maxJobs": 1-15
    }    
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST account/midjourney](/docs/api-v2/post-account-midjourney).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [channel: string]: {
    discord: string, 
    channel: string,
    maxJobs: number,
    pendingModMessage: string
  }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/account/midjourney \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v2/account/midjourney"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v2/account/midjourney"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-jobs-cancel ===
Document URL: https://useapi.net/docs/api-v2/get-jobs-cancel

## Cancel Midjourney job
<small>December 2023 (October 7, 2024)</small>

---

Cancel execution of job created by 
- [jobs/imagine](/docs/api-v2/post-jobs-imagine)
- [jobs/button](/docs/api-v2/post-jobs-button)
- [jobs/blend](/docs/api-v2/post-jobs-blend)
- [jobs/describe](/docs/api-v2/post-jobs-describe)
- [jobs/seed_async](/docs/api-v2/post-jobs-seed_async)
> **https://api.useapi.net/v2/jobs/cancel/?jobid=`jobid`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameter
`jobid` is **required**, use value returned by 
  - [jobs/imagine](/docs/api-v2/post-jobs-imagine)
  - [jobs/button](/docs/api-v2/post-jobs-button)
  - [jobs/blend](/docs/api-v2/post-jobs-blend)
  - [jobs/describe](/docs/api-v2/post-jobs-describe)
  - [jobs/seed_async](/docs/api-v2/post-jobs-seed_async)

##### Responses 
**200**

```json
{
    "jobid": "<jobid>",
    "status": "cancelled"
}   "code": 200
```

**400**

**400 Bad Request**

```json
{
    "error": "Query param jobid not provided",
    "code": 400
}
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**

**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**

**404 Not Found**

```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  status: 'created' | 'started' | 'moderated' | 'progress' | 
          'completed' | 'failed' | 'cancelled',
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/jobs/cancel/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const jobid = "jobid returned by jobs/imagine or jobs/button";      
const apiUrl = `https://api.useapi.net/v2/jobs/cancel/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
jobid = "jobid returned by jobs/imagine or jobs/button"
apiUrl = f"https://api.useapi.net/v2/jobs/cancel/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-jobs-jobid ===
Document URL: https://useapi.net/docs/api-v2/get-jobs-jobid

## Retrieve job status and results
<small>December 2023 (September 1, 2025)</small>

---

Use this endpoint to retrieve status and results of 
- [jobs/imagine](/docs/api-v2/post-jobs-imagine)
- [jobs/button](/docs/api-v2/post-jobs-button)
- [jobs/blend](/docs/api-v2/post-jobs-blend)
- [jobs/describe](/docs/api-v2/post-jobs-describe)
- [jobs/info](/docs/api-v2/post-jobs-info)
- [jobs/relax](/docs/api-v2/post-jobs-relax)
- [jobs/fast](/docs/api-v2/post-jobs-fast)
- [jobs/turbo](/docs/api-v2/post-jobs-turbo)
- [jobs/variability](/docs/api-v2/post-jobs-variability)
- [jobs/remix](/docs/api-v2/post-jobs-remix)
- [jobs/seed_async](/docs/api-v2/post-jobs-seed_async)

If you specified optional parameter [`replyUrl`](/docs/api-v2/post-jobs-imagine#request-body) you technically do not need to use this endpoint to retrieve results since API will call provided `replyUrl` once job generation completed.

**Important** The API checks Discord periodically - every 15 seconds (and up to 60 seconds in rare cold start cases) - to update the statuses and results of all currently running jobs. This polling interval is set for safety reasons to help prevent issues with Discord and Midjourney, such as bans or excessive request rates.

Jobs lifespan guaranteed to be at least 31 days, after that they will be expired and may be recycled.
> **https://api.useapi.net/v2/jobs/?jobid=`jobid`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameter
`jobid` is **required**, use the value returned by the following jobs:
  - [jobs/imagine](/docs/api-v2/post-jobs-imagine)
  - [jobs/button](/docs/api-v2/post-jobs-button)
  - [jobs/blend](/docs/api-v2/post-jobs-blend)
  - [jobs/describe](/docs/api-v2/post-jobs-describe)
  - [jobs/seed_async](/docs/api-v2/post-jobs-seed_async)

You can also retrieve results for the jobs listed below, even though they will return the final result with the original call:
  - [jobs/info](/docs/api-v2/post-jobs-info)
  - [jobs/relax](/docs/api-v2/post-jobs-relax) 
  - [jobs/fast](/docs/api-v2/post-jobs-fast)
  - [jobs/turbo](/docs/api-v2/post-jobs-turbo)
  - [jobs/variability](/docs/api-v2/post-jobs-variability)
  - [jobs/remix](/docs/api-v2/post-jobs-remix)

##### Responses 
**200**

**200 OK**

If field `status` value is *created*, *started* or *progress* wait in a loop for **at least** 10..30 seconds and retry again. When completed retrieve generated image from `attachments` field. If you're planning to take advantage of Discord CDN to host attachments, take a look at our [Discord CDN Proxy](/docs/articles/discord-cdn-proxy) article.

Field `content` contains message generated by Midjourney reflecting current generation parameters and progress.   
Optional array `embeds` contains additional information.    
Optional array `imageUx` contains separate image URLs to the upscaled images where available.  
Optional array `imageUx` contains separate video URLs to the upscaled videos where available.  

To retrieve `imageUx` and `videoUx` URLs, use [GET proxy/cdn-midjourney](/docs/api-v2/get-proxy-cdn-midjourney). Both URLs are behind CloudFlare, and unless you plan to display them as part of an HTML page served via a standard browser context, you will need to use the provided proxy above to download those images and videos.

>⚠️ Security consideration when using `videoUx` and `imageUx` URLs:  
URLs in both arrays follow this format: `https://cdn.midjourney.com/<GUID>/…`. They contain a job GUID which can be traced back to your account and will expose your account details such as your Discord account name and email. Exercise caution when posting these URLs publicly. You may want to save the URL content locally and serve it from your own origin, or proxy the links to obfuscate the original URLs.

```json
{
    "jobid": "job:20250822143812123-user:12345-channel:1122334455667788990-bot:midjourney",
    "verb": "imagine",
    "status": "completed",
    "created": "2025-08-22T14:38:12.123Z",
    "updated": "2025-08-22T14:40:05.889Z",
    "prompt": "https://modern.art/abcdef/bird.webp Tweety Bird spins kettlebell with one hand around once and hurls the kettlebell directly at the camera in a slow motion --iw 2 --ar 3:2 --motion low --video",
    "replyRef": "2025-08-22T14:38:10.456Z",
    "replyUrl": "https://webhook.site/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3",
    "channel": "1122334455667788990",
    "maxJobs": 3,
    "discord": "NDE...secured...ABC",
    "messageId": "1522889900112233445",
    "content": "**<https://s.mj.run/aBcDeF-ghIj> https://fluxpro.ai/abcdef/bird.webp Tweety Bird spins kettlebell with one hand around once and hurls the kettlebell directly at the camera in a slow motion --iw 2 --ar 3:2 --motion low --video 1** - <@987654321098765432> [(Open on website for full quality)](<https://midjourney.com/jobs/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3>) (fast)",
    "timestamp": "2025-08-22T14:39:55.777000+00:00",
    "attachments": [
        {
            "proxy_url": "https://media.discordapp.net/attachments/….webp?ex=…&is=…&hm=…&",
            "height": 768,
            "content_type": "image/webp",
            "placeholder": "…",
            "placeholder_version": 1,
            "filename": "….webp",
            "size": 3105492,
            "url": "https://cdn.discordapp.com/attachments/….webp?ex=…&is=…&hm=…&",
            "width": 512,
            "flags": 32,
            "content_scan_version": 2,
            "id": "1522889900112233445"
        }
    ],
    "buttons": [
        "U1",
        "U2",
        "U3",
        "U4",
        "🔄"
    ],
    "videoUx": [
        {
            "id": 1,
            "url": "https://cdn.midjourney.com/video/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3/0.mp4"
        },
        {
            "id": 2,
            "url": "https://cdn.midjourney.com/video/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3/1.mp4"
        },
        {
            "id": 3,
            "url": "https://cdn.midjourney.com/video/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3/2.mp4"
        },
        {
            "id": 4,
            "url": "https://cdn.midjourney.com/video/b4d8e1a0-5c6f-4a3b-9e1d-f8c7b6a5d4e3/3.mp4"
        }
    ],
    "code": 200
}
```

**400**

**400 Bad Request**

```json
{
    "error": "Query param jobid not provided",
    "code": 400
}
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**

**404 Not Found**

```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```

**410**

**410 Gone**

```json
{
    "error": "Job has expired",
    "code": 410
}
```

##### Model

To learn more about `status: moderated`, see [Midjourney moderation system](/docs/articles/discord-api-part-2#midjourney-moderation-system).

```typescript
{ // TypeScript, all fields are optional
  jobid: string,
  parentJobId: string,
  verb: 'imagine' | 'button' | 'blend' | 'describe' | 
        'info' | 'relax' | 'fast' | 'turbo' | 'variability' | 'remix' | 'seed' | 'seed_async',
  status: 'created' | 'started' | 'moderated' | 'progress' | 
          'completed' | 'failed' | 'cancelled',
  seed: { 
    value: number, // Parsed seed number
    content: string, // Original content message returned by Midjourney for a seed request
    attachments: {  // Seed images
      id: string,
      content_type: string,
      filename: string,
      url: string,
      proxy_url: string,
      size: number,
      width: number,
      height: number 
    }[]
  },          
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  prompt: string,
  blendUrls: string[],
  blendDimensions: 'Portrait' | 'Square' | 'Landscape',    
  describeUrl: string,
  button: 'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' | 'V3' | 'V4' |
            '⬅️' | '➡️' | '⬆️' | '⬇️' | '🔄' |
            'Vary (Region)' | 'Vary (Strong)' | 'Vary (Subtle)' | 'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Make Square' |
            'Upscale (2x)' | 'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' |
            'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' | 'Redo Upscale (Creative)' |
            'Make Variations' | 'Remaster' | 'Custom Zoom' | 
            'Animate (Low motion)' | 'Animate (High motion)' | // Added July 28, 2025
            'Extend (Low motion)' | 'Extend (High motion)', // Added July 28, 2025
  children: {
    messageId: string,
    button: 'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' | 'V3' | 'V4' |
            '⬅️' | '➡️' | '⬆️' | '⬇️' | '🔄' |
            'Vary (Region)'| 'Vary (Strong)' | 'Vary (Subtle)' | 'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Make Square' |
            'Upscale (2x)' | 'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' |
            'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' | 'Redo Upscale (Creative)' |
            'Make Variations' | 'Remaster' | 'Custom Zoom' |
            'Animate (Low motion)' | 'Animate (High motion)' | // Added July 28, 2025
            'Extend (Low motion)' | 'Extend (High motion)', // Added July 28, 2025
    jobid: string 
  }[],
  buttons: 
  [
      'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' | 'V3' | 'V4' |
      '⬅️' | '➡️' | '⬆️' | '⬇️' | '🔄' |
      'Vary (Region)'| 'Vary (Strong)' | 'Vary (Subtle)' | 'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Make Square'
      'Upscale (2x)' | 'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' |
      'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' | 'Redo Upscale (Creative)' |
      'Make Variations' | 'Remaster' | 'Custom Zoom' |
      'Animate (Low motion)' | 'Animate (High motion)' | // Added July 28, 2025
      'Extend (Low motion)' | 'Extend (High motion)', // Added July 28, 2025
  ],
  imageUx: { id: number, url: string }[], // Added September 1, 2025. Upscaled image URLs for Ux buttons 
  videoUx: { id: number, url: string }[], // Added September 1, 2025. Upscaled video URLs for Ux buttons when --video is used
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  maxJobs: number,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  timestamp: string,
  attachments: {
    id: string,
    content_type: string,
    filename: string,
    url: string,
    proxy_url: string,
    size: number,
    width: number,
    height: number 
  }[],
  embeds: {
    type: string,
    description: string,
    image: {
      url: string,
      proxy_url: string,
      width: number,
      height: number 
    } 
  }[], 
  error: string,
  errorDetails: string,
  replyUrl: string,
  replyRef: string,
  code: 200
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/jobs/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const jobid = "jobid returned by jobs/imagine or jobs/button";      
const apiUrl = `https://api.useapi.net/v2/jobs/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
jobid = "jobid returned by jobs/imagine or jobs/button"
apiUrl = f"https://api.useapi.net/v2/jobs/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-jobs ===
Document URL: https://useapi.net/docs/api-v2/get-jobs

## Get list of currently executing Midjourney jobs
<small>December 2023</small>

---
> **https://api.useapi.net/v2/jobs**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 
**200**

**200 OK**

```json
[ "<jobid>", "<jobid>", "<jobid>" ]
```

**401**

**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**

**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

##### Model
```typescript
// TypeScript
string[]
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v2/jobs \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v2/jobs`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v2/jobs"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/get-proxy-cdn-midjourney ===
Document URL: https://useapi.net/docs/api-v2/get-proxy-cdn-midjourney
## Proxy asset retrieval from https://cdn.midjourney.com
<small>September 12, 2025</small>

---

This endpoint allows you to fetch images and videos from `https://cdn.midjourney.com/` through the useapi.net proxy. Use it to retrieve `imageUx` and `videoUx` URLs returned by
[GET jobs/?jobid=`jobid`](/docs/api-v2/get-jobs-jobid) or any other assets hosted on `https://cdn.midjourney.com/`.

The Midjourney CDN requires standard browser headers—specifically the `User-Agent` header—to serve assets. Without it, Cloudflare will block the request. This proxy endpoint adds these headers automatically.

##### Alternative: Direct CDN Access

You can skip the proxy and fetch assets directly from `https://cdn.midjourney.com/` by including the necessary headers:

**Curl**
``` bash
curl "https://cdn.midjourney.com/example-image.jpg" \
     -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36" \
     -H "Accept: */*" \
     -H "Accept-Encoding: gzip, deflate, br" \
     -H "Connection: keep-alive" \
     --output image.jpg
```

**JavaScript**
``` javascript
const cdnUrl = "https://cdn.midjourney.com/example-image.jpg";

const headers = new Headers();
headers.set('User-Agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36');
headers.set('Accept', '*/*');
headers.set('Accept-Encoding', 'gzip, deflate, br');
headers.set('Connection', 'keep-alive');

const response = await fetch(cdnUrl, { headers });
const blob = await response.blob();

// Save to file (Node.js)
const fs = require('fs');
const buffer = await blob.arrayBuffer();
fs.writeFileSync('image.jpg', Buffer.from(buffer));
```

**Python**
``` python
import requests

cdnUrl = "https://cdn.midjourney.com/example-image.jpg"

headers = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36',
    'Accept': '*/*',
    'Accept-Encoding': 'gzip, deflate, br',
    'Connection': 'keep-alive'
}

response = requests.get(cdnUrl, headers=headers)

# Save image/video content
with open('image.jpg', 'wb') as f:
    f.write(response.content)
```

**Note:** The `User-Agent` header is critical—without it, Cloudflare will block your request.

---
> **https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=`https://cdn.midjourney.com/…`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameter
- `cdnUrl` is **required** and must be a valid asset URL starting with `https://cdn.midjourney.com/`

##### Responses 

**200**

**200 OK**

Returns the proxied content from the Midjourney CDN with appropriate headers.

**400**
**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**403**
**403 Forbidden**

Cloudflare may occasionally block requests even with proper headers. This is typically temporary and can be resolved with retry logic.

**Recommendation:** Implement retry logic with exponential backoff when encountering 403 errors, or better yet, implement your own direct CDN access using the headers shown in the "Alternative: Direct CDN Access" section above for greater control and reliability.

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=https://cdn.midjourney.com/example-image.jpg"
```

**JavaScript**
``` javascript
const cdnUrl = "https://cdn.midjourney.com/example-image.jpg";
const apiUrl = `https://api.useapi.net/v1/proxy/cdn-midjourney/`; 
const api_token = "API token";
const response = await fetch(`${apiUrl}?cdnUrl=${encodeURIComponent(cdnUrl)}`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${api_token}`
    }
});

const result = await response.blob(); // For image/video content
console.log("response", {response, result});
```

**Python**
``` python
import requests
cdnUrl = "https://cdn.midjourney.com/example-image.jpg"
apiUrl = f"https://api.useapi.net/v1/proxy/cdn-midjourney/"
api_token = "API token"
headers = {
    "Authorization": f"Bearer {api_token}"
}

params = {
    "cdnUrl": cdnUrl
}

response = requests.get(apiUrl, headers=headers, params=params)
print(response.status_code, response.headers)

# Save image/video content
with open('image.jpg', 'wb') as f:
    f.write(response.content)
```

=== URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel-reset ===
Document URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel-reset
## Reset `pendingModMessage` field for Midjourney account `channel` 
<small>December 2023 (March 3, 2026)</small>

---

If the API detects a pending moderation message or a CAPTCHA account verification request from Midjourney, it will flag the corresponding account by setting the `pendingModMessage` field to the message provided by Midjourney. This will effectively remove that account from the rotation. Any attempts to make API calls using this account will result in a 596 response code, indicating that the account is under moderation and cannot be used for API interactions. 

The best course of action is to log into your Discord account and address the Midjourney moderation message to avoid a potential ban on your Midjourney account. Once you have acknowledged the message, you can use this endpoint to reset the Midjourney account and return it to the rotation.

If a CAPTCHA account verification request was issued by MidJourney, you may need to manually execute `/imagine` to display the dialog with verification links.

Please note that the API will also send you an email notification when a Midjourney pending moderation message or CAPTCHA account verification request is detected.
> **https://api.useapi.net/v2/account/midjourney/`channel`/reset**

The `channel` value should correspond to an account configured previously via a [POST](/docs/api-v2/post-account-midjourney-channel-reset) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

**596**
**596 Pending mod message**

Returned when the channel has an active ban that has not yet expired, or a permanent ban. Reset is not allowed until the ban expires.

```json
{
  "error": "You have been temporarily blocked from accessing Midjourney.\nYour block ends <t:1772509411:R> (2026-03-03 03:43 UTC)",
  "expiresIn": "2 days 5 hours 30 minutes",
  "code": 596
}
```

For permanent bans, `expiresIn` will be `"permanent"`. Delete this account via [DEL /account/midjourney/channel](/docs/api-v2/del-account-midjourney-channel) and configure a new Discord account.

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  expiresIn: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/account/midjourney/<channel>/reset 
```

**JavaScript**
``` javascript
const channel = "Previously configured channel id with pendingModMessage"; 
const apiUrl = `https://api.useapi.net/v2/account/midjourney/${channel}/reset`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
channel = "Previously configured channel id with pendingModMessage"
apiUrl = f"https://api.useapi.net/v2/account/midjourney/{channel}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.post(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel ===
Document URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel
## Create or update Midjourney account information <span class="required-input-field"><b>(retired)</b></span>  
<small>December 2023 (August 5, 2025)</small>

---

<span class="required-input-field"><b>Important</b></span>  
**We will be officially sunsetting this endpoint in January 2025.  
Please use [POST account/midjourney](/docs/api-v2/post-account-midjourney) instead.**

For your convenience, you can specify your Midjourney configuration values under your account so that you no longer need to provide them with every API call. If you specify multiple Midjourney accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Discord / Midjourney.
> **https://api.useapi.net/v2/account/midjourney/`channel`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "discord": "Discord token",
    "channel": "Discord channel id",
    "maxJobs": 1-15,
}
```

- `discord`, `channel` are **required**. Please see [Setup Midjourney](/docs/start-here/setup-midjourney) for details. 

- `channel` value specified in the request body **must match** the channel value specified in the URL path https://api.useapi.net/v2/account/midjourney/`channel`.

- `maxJobs` is **required**. This value should be the same or less than your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison). Currently, it should be 3 or less for Basic and Standard plans and 15 or less for Pro and Mega plans.  
**Important** Specifying a higher number than supported by your Midjourney subscription will prevent API from functioning properly.  

##### Responses 

**204**
**204 No Content** 

**400**
**400 Bad Request**
```json
{
  "error": 
    "Required param discord is missing or empty"
    "Required param channel is missing or empty"
    "Required param channel (<channel>) is not valid Discord channel id"
    "Required param channel (<channel>) not matching to /midjourney/channel (/midjourney/<channel>)"
    "Required param maxJobs is missing or empty"
    "Required param maxJobs <maxJobs> can't be more that <maxConcurrentJobs>"
    "Channel <channel> configuration has same discord value"
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string, 
  channel: string,
  maxJobs: number,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/account/midjourney/<channel> \
     -d '{"discord": "…", "channel": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const channel = "Discord channel id";      
const apiUrl = `https://api.useapi.net/v2/account/midjourney/${channel}`; 
const token = "API token";
const discord = "Discord token";
const maxJobs = 3;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  discord, channel, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
channel = "Discord channel id"
apiUrl = f"https://api.useapi.net/v2/account/midjourney/{channel}" 
token = "API token"
discord = "Discord token"
maxJobs = 3
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "discord": f"{discord}", 
    "channel": f"{channel}",
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-account-midjourney ===
Document URL: https://useapi.net/docs/api-v2/post-account-midjourney
## Create or update Midjourney account information
<small>December 2023 (August 5, 2025)</small>

---

You must configure a Midjourney API account before making calls using the Midjourney API. If you specify multiple Midjourney accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Discord / Midjourney.
> **https://api.useapi.net/v2/account/midjourney**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "discord": "Discord token",
    "maxJobs": 1-15,
}
```

- `discord` is **required**. Please see [Setup Midjourney](/docs/start-here/setup-midjourney) for details. 

- `maxJobs` is optional and will be set to 3 if not provided. This value should be equal to or less than the Maximum Concurrent Jobs allowed by your Midjourney subscription plan ([see plan comparison](https://docs.midjourney.com/docs/plans#plan-comparison)). Currently, it should be 3 or less for Basic and Standard plans, and 15 or less for Pro and Mega plans.   
  **Important:** Specifying a higher number than supported by your Midjourney subscription will prevent the API from functioning properly.

##### Responses 

**200**
**200 OK** 

Existing Midjourney API account was updated.

```json 
{
    "discord": "<discord token>",
    "channel": "<Midjourney private channel id>",
    "maxJobs": 1-15
}
```

**201**
**201 Created** 

New Midjourney API account was created.

```json 
{
    "discord": "<discord token>",
    "channel": "<Midjourney private channel id>",
    "maxJobs": 1-15
}
```

**400**
**400 Bad Request**
```json
{
  "error": 
    "Required param discord is missing or empty"
    "Required param maxJobs <maxJobs> can't be more that <maxConcurrentJobs>"
    "Channel <channel> configuration has same discord value"
    "`Midjourney bot not configured"
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": 
        "Account has no subscription or subscription expired"
        "Subscription quantity exceeded, see https://useapi.net/docs/subscription",
    "code": 402
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string, 
  channel: string,
  maxJobs: number,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/account/midjourney \
     -d '{"discord": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const apiUrl = `https://api.useapi.net/v2/account/midjourney`; 
const token = "API token";
const discord = "Discord token";
const maxJobs = 3;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  discord, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = f"https://api.useapi.net/v2/account/midjourney" 
token = "API token"
discord = "Discord token"
maxJobs = 3
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "discord": f"{discord}", 
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-blend ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-blend
## Midjourney [/blend](https://docs.midjourney.com/docs/blend) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/blend](https://docs.midjourney.com/docs/blend) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [jobs/?jobid=`jobid`](/docs/api-v2/get-jobs-jobid) endpoint.  

Your current [Midjourney Settings and Presets](https://docs.midjourney.com/docs/settings-and-presets) will be used, log in to your Discord Midjourney account to adjust them to your liking.  

It is **important** not to use the Midjourney account setup for API access for any purposes other than its intended use, such as executing `/imagine` or any other Midjourney commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the Midjourney account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v2/jobs/blend**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "blendUrls": ["URL #1", "URL #2", "URL #3", "URL #4", "URL #5"],
    "blendDimensions": "Portrait, Square or Landscape",
    "channel": "Discord channel id",
    "maxJobs": 3,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `blendUrls` is **required**, must contain at least 2 valid URL image links.  
  Up to 5 URL image links supported.  

- `blendDimensions` is optional, can be `Portrait`, `Square` or `Landscape`

- `channel` is optional, if not provided randomly selected available account from [account/midjourney](/docs/api-v2/get-account-midjourney) will be used. See [Setup Midjourney](/docs/start-here/setup-midjourney) for details. Specify the `channel` value when you wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney).

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 3.  
  This value should be the same or less than your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison). Currently, it should be 3 or less for Basic and Standard plans and 15 or less for Pro and Mega plans.  
**Important** Specifying a higher number than supported by your Midjourney subscription will prevent API from functioning properly.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank">**200 OK**

Use returned `jobid` to [retrieve job status and results](/docs/api-v2/get-jobs-jobid). `content` contains message generated by Midjourney reflecting current generation parameters and progress.

If you want to retrieve four separate upscaled images once job completed successfully execute [seed](/docs/api-v2/post-jobs-seed).

```json
{
    "jobid": "<jobid>",
    "verb": "blend",
    "status": "started",
    "created": "2023-10-06T18:36:37.963Z",
    "updated": "2023-10-06T18:36:50.401Z",
    "blendUrls": [
        "https://...1.png",
        "https://...2.jpg"
    ],
    "blendDimensions": "Landscape",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "**<https://...1> <https://...2> --s 750 --v 5.2** - <@Discord user id> (Waiting to start)",
    "timestamp": "2023-10-06T18:36:48.875000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
    "error": 
        "blendUrls is missing" 
        "blendUrls should contain at least 2 urls" 
        "blendUrls should contain no more than 5 urls"
        "blendUrls #<ind> contains empty value" 
        "blendDimensions should be one of Portrait, Square, Landscape"
        "GET <url> failed with HTTP status <status>. Response body <body>"        
        "<url> unknown mime type"
        "<replyRef | replyUrl> is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**
```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**422**
**422 Unprocessable Content**

Moderated image link, see [Midjourney moderation system](/docs/articles/discord-api-part-2#midjourney-moderation-system).

```json
{
    "error": "Invalid link",
    "errorDetails": "Request cancelled due to image filters.",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. The API query is full and can not accept new [jobs/blend](#midjourney-blend-command) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). 
```json
{
    "error": "Maximum of <maxJobs> jobs executing in parallel supported",
    "executingJobs": [
      "<jobid>",
      "<jobid>",
      "<jobid>"
    ],
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**504**
**504 Job queued**

Job queued. The API will not be able to track the progress of this job, although it will still be processed by Midjourney. You may want to adjust the `maxJobs` number to a lower value for the next several minutes.  

You should not receive this error under normal circumstances unless you have specified a `maxJobs` parameter higher than your Midjourney subscription supports, or if you are using the Midjourney bot outside of API interactions. On occasions when Midjourney is releasing new updates or experiencing technical issues, jobs may be paused for an extended period of time. Our API will mark all jobs running over 30 minutes as `failed`. When Midjourney comes back online, it will attempt to complete previously paused jobs, and you may encounter a conflict if you try to submit a new job at the same time. Although this happens very rarely, we have decided to add an extra layer to ensure such cases are detected. 

```json
{
    "error": "Job queued",
    "jobid": "<jobid>",
    "status": "failed",
    "code": 504
}
```

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "blend",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "blendUrls": [
        "https://...1.png",
        "https://...2.jpg"
    ],
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'blend',
  status: 'started' | 'moderated' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  blendUrls: string[],
  blendDimensions: 'Portrait' | 'Square' | 'Landscape',
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/blend \
     -d '{"blendUrls": ["…", "…"], "channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/blend"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const blendUrls = ["https://url.1", "https://url.2"];
data.body = JSON.stringify({ 
  blendUrls, channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/blend" 
token = "API token"
channel = "Discord channel id"
blendUrls = ["https://url.1", "https://url.2"]
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "blendUrls": blendUrls,
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-button ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-button
## Midjourney [upscale or create variations](https://docs.midjourney.com/docs/quick-start#8-upscale-or-create-variations) and [enhance or modify](https://docs.midjourney.com/docs/quick-start#9-enhance-or-modify-your-image) buttons
<small>December 2023 (February 19, 2026)</small>

---

Use this endpoint to execute Midjourney [upscale or create variations](https://docs.midjourney.com/docs/quick-start#8-upscale-or-create-variations) and [enhance or modify](https://docs.midjourney.com/docs/quick-start#9-enhance-or-modify-your-image) button commands. Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [jobs/?jobid=`jobid`](/docs/api-v2/get-jobs-jobid) endpoint.  

We provide full support for **video generation**, including the buttons `Animate (High motion)`, `Animate (Low motion)`, `Extend (High motion)`, and `Extend (Low motion)`. Please refer to the [official documentation](https://docs.midjourney.com/hc/en-us/articles/37460773864589-Video) for details.

Your current [Midjourney Settings and Presets](https://docs.midjourney.com/docs/settings-and-presets) will be used, log in to your Discord Midjourney account to adjust them to your liking.  

It is **important** not to use the Midjourney account setup for API access for any purposes other than its intended use, such as executing `/imagine` or any other Midjourney commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the Midjourney account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v2/jobs/button**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "jobid": "jobid",
    "button": "button",
    "prompt": "required for button Custom Zoom",
    "maxJobs": 3,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `jobid` is **required**, `jobid` of successfully completed (`status` set to [*completed*](/docs/api-v2/get-jobs-jobid#model)) [jobs/imagine](/docs/api-v2/post-jobs-imagine), [jobs/button](#midjourney-upscale-or-create-variations-and-enhance-or-modify-buttons) or [jobs/blend](/docs/api-v2/post-jobs-blend) job. 

- `button` is **required**, button from buttons array of job referenced via `jobid` above, see [*button*](#model).

- `prompt` is optional, it is required for `Custom Zoom` button, see [Custom Zoom](https://docs.midjourney.com/docs/zoom-out#custom-zoom).  
  When [Remix Mode](https://docs.midjourney.com/docs/remix) is active, the buttons `V1`, `V2`, `V3`, `V4`, `Vary (Region)`, `Vary (Strong)`, `Vary (Subtle)`, 
    ⬅️, ➡️, ⬆️, ⬇️ and 🔄 also accept a prompt. 

- `mask` is required for `Vary (Region)` button, must be base64-encoded **WebP** format, see [Vary Region mask editor](/docs/api-v2/vary-region-mask-editor).  

- `maxJobs` is optional, if provided will override `maxJobs` value of referenced above `jobid`, if not provided defaulted to 3.  
  This value should be the same or less than your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison). Currently, it should be 3 or less for Basic and Standard plans and 15 or less for Pro and Mega plans.  
**Important** Specifying a higher number than supported by your Midjourney subscription will prevent API from functioning properly.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve job status and results](/docs/api-v2/get-jobs-jobid).

If you want to retrieve four separate upscaled images once job completed successfully execute [seed_async](/docs/api-v2/post-jobs-seed_async).

```json
{
    "jobid": "<jobid>",
    "verb": "button",
    "status": "started",
    "created": "2023-09-09T20:19:57.073Z",
    "updated": "2023-09-09T20:19:58.536Z",
    "button": "V1",
    "parentJobId": "<jobid>",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "content": "<Discord message content>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T20:19:57.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
    "error": 
      "button <button> not supported"
      "<jobid | button> is missing"
      "<replyRef | replyUrl> is too long"
    "code": 400
}
```

```json
{
    "error": "button <button> not found in job <jobid> buttons <array>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**
**404 Not Found**
```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```

**409**
**409 Conflict**
```json
{
  "error": "Button <U1 | U2 | U3 | U4> already executed by job <jobid>",
  "button": "<button>",
  "jobid": "<jobid>",
  "code": 409
}
```

**422**
**422 Unprocessable Content**

Moderated message or invalid prompt params, see [Midjourney moderation system](/docs/articles/discord-api-part-2#midjourney-moderation-system).

```json
{
    "error": "Action needed to continue",
    "errorDetails": "Sorry! Our AI moderators feel your prompt might be against our community standards.",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

```json
{
    "error": "Invalid parameter",
    "errorDetails": "Unrecognized parameter(s): `size`",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [jobs/button](#midjourney-upscale-or-create-variations-and-enhance-or-modify-buttons) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). Wait in a loop for **at least** 10..30 seconds and retry again.
```json
{
    "error": "Maximum of <maxJobs> jobs executing in parallel supported",
    "executingJobs": [
      "<jobid>",
      "<jobid>",
      "<jobid>"
    ],
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**504**
**504 Job queued**

Job queued. The API will not be able to track the progress of this job, although it will still be processed by Midjourney. You may want to adjust the `maxJobs` number to a lower value for the next several minutes.  

You should not receive this error under normal circumstances unless you have specified a `maxJobs` parameter higher than your Midjourney subscription supports, or if you are using the Midjourney bot outside of API interactions. On occasions when Midjourney is releasing new updates or experiencing technical issues, jobs may be paused for an extended period of time. Our API will mark all jobs running over 30 minutes as `failed`. When Midjourney comes back online, it will attempt to complete previously paused jobs, and you may encounter a conflict if you try to submit a new job at the same time. Although this happens very rarely, we have decided to add an extra layer to ensure such cases are detected. 

```json
{
    "error": "Job queued",
    "jobid": "<jobid>",
    "status": "failed",
    "code": 504
}
```

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "button",
    "button": "V1",
    "parentJobId": "<jobid>",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and reset the /account pendingModMessage before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'button',
  status: 'started' | 'moderated' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  button: 'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' | 'V3' | 'V4' |
          '⬅️' | '➡️' | '⬆️' | '⬇️' | '🔄' |
          'Vary (Region)' | 'Vary (Strong)' | 'Vary (Subtle)' | 'Zoom Out 1.5x' | 'Zoom Out 2x' | 'Make Square' |
          'Upscale (2x)' | 'Upscale (4x)' | 'Upscale (Subtle)' | 'Upscale (Creative)' |
          'Redo Upscale (2x)' | 'Redo Upscale (4x)' | 'Redo Upscale (Subtle)' | 'Redo Upscale (Creative)' |
          'Make Variations' | 'Remaster' | 'Custom Zoom' |
          'Animate (Low motion)' | 'Animate (High motion)' | // Added July 28, 2025
          'Extend (Low motion)' | 'Extend (High motion)', // Added July 28, 2025
  prompt: string, // Required for button Custom Zoom https://docs.midjourney.com/docs/zoom-out#custom-zoom
  parentJobId: string,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/button \
     -d '{"jobid": "…", "button": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/button"; 
const token = "API token";
const jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid";      
const button = "Button from buttons array of above jobid";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  jobid, button
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/button" 
token = "API token"
jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid"
button = "Button from buttons array of above jobid"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "jobid": f"{jobid}", 
    "button": f"{button}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-describe ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-describe
## Midjourney [/describe](https://docs.midjourney.com/docs/describe) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/describe](https://docs.midjourney.com/docs/describe) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [jobs/?jobid=`jobid`](/docs/api-v2/get-jobs-jobid) endpoint.  

Your current [Midjourney Settings and Presets](https://docs.midjourney.com/docs/settings-and-presets) will be used, log in to your Discord Midjourney account to adjust them to your liking.  

It is **important** not to use the Midjourney account setup for API access for any purposes other than its intended use, such as executing `/imagine` or any other Midjourney commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the Midjourney account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v2/jobs/describe**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "describeUrl": "URL",
    "channel": "Discord channel id",
    "maxJobs": 3,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `describeUrl` is **required**, must contain valid URL image link.  

- `channel` is optional, if not provided randomly selected available account from [account/midjourney](/docs/api-v2/get-account-midjourney) will be used. See [Setup Midjourney](/docs/start-here/setup-midjourney) for details. Specify the `channel` value when you wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney).  

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 3.  
  This value should be the same or less than your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison). Currently, it should be 3 or less for Basic and Standard plans and 15 or less for Pro and Mega plans.  
**Important** Specifying a higher number than supported by your Midjourney subscription will prevent API from functioning properly.   

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve job status and results](/docs/api-v2/get-jobs-jobid). `content` contains message generated by Midjourney reflecting current generation parameters and progress.
```json
{
    "jobid": "<jobid>",
    "verb": "describe",
    "status": "started",
    "created": "2023-10-06T18:36:37.963Z",
    "updated": "2023-10-06T18:36:50.401Z",
    "describeUrl": "https://...1.png",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "messageId": "<Discord message id>",
    "content": "",
    "timestamp": "2023-10-06T18:36:48.875000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
    "error": 
        "describeUrl is missing" 
        "describeUrl is empty" 
        "GET <url> failed with HTTP status <status>. Response body <body>"
        "<url> unknown mime type"
        "<replyRef | replyUrl> is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**
```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**422**
**422 Unprocessable Content**

Moderated image link, see [Midjourney moderation system](/docs/articles/discord-api-part-2#midjourney-moderation-system).

```json
{
    "error": "Invalid link",
    "errorDetails": "Request cancelled due to image filters.",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [jobs/describe](#midjourney-describe-command) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). Wait in a loop for **at least** 10..30 seconds and retry again.
```json
{
    "error": "Maximum of <maxJobs> jobs executing in parallel supported",
    "executingJobs": [
      "<jobid>",
      "<jobid>",
      "<jobid>"
    ],
    "code": 429
}
```
2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.

```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**504**
**504 Job queued**

Job queued. The API will not be able to track the progress of this job, although it will still be processed by Midjourney. You may want to adjust the `maxJobs` number to a lower value for the next several minutes.  

You should not receive this error under normal circumstances unless you have specified a `maxJobs` parameter higher than your Midjourney subscription supports, or if you are using the Midjourney bot outside of API interactions. On occasions when Midjourney is releasing new updates or experiencing technical issues, jobs may be paused for an extended period of time. Our API will mark all jobs running over 30 minutes as `failed`. When Midjourney comes back online, it will attempt to complete previously paused jobs, and you may encounter a conflict if you try to submit a new job at the same time. Although this happens very rarely, we have decided to add an extra layer to ensure such cases are detected. 

```json
{
    "error": "Job queued",
    "jobid": "<jobid>",
    "status": "failed",
    "code": 504
}
```

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "blend",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "describeUrl": "https://...1.png",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'describe',
  status: 'started' | 'moderated' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  describeUrl: string,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/describe \
     -d '{"describeUrl": "…", "channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/describe"; 
const token = "API token";
const describeUrl = "https://url.1";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  describeUrl, channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/describe" 
token = "API token"
describeUrl = "https://url.1"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "describeUrl": f"{describeUrl}",
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-fast ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-fast
## Midjourney [/fast](https://docs.midjourney.com/docs/fast-relax) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/fast](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/fast**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional **if only one** Midjourney account configured under [account/midjourney](/docs/api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](/docs/api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "fast",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "Done! Note that once you exhaust your fast hours, you can purchase more on the website: <https://midjourney.com/account>. To conserve your fast hours, use `/relax` to switch back to relax mode.",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "fast",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'fast',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string,
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/fast \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/fast"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/fast" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-imagine ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-imagine
## Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command 
<small>December 2023 (September 1, 2025)</small>

---

Use this endpoint to submit the Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [jobs/?jobid=`jobid`](/docs/api-v2/get-jobs-jobid) endpoint.  

We provide full support for **video generation**, including all video-specific parameters such as `--video`, `--motion low`, `--motion high`, `--raw`, `--loop`, and `--end`, as well as the buttons `Animate (High motion)`, `Animate (Low motion)`, `Extend (High motion)`, and `Extend (Low motion)`. Please refer to the [official documentation](https://docs.midjourney.com/hc/en-us/articles/37460773864589-Video) for details.

Your current [Midjourney Settings and Presets](https://docs.midjourney.com/docs/settings-and-presets) will be used, log in to your Discord Midjourney account to adjust them to your liking.  

It is **important** not to use the Midjourney account setup for API access for any purposes other than its intended use, such as executing `/imagine` or any other Midjourney commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the Midjourney account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly.
> **https://api.useapi.net/v2/jobs/imagine**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "prompt": "Midjourney prompt",
    "channel": "Discord channel id",
    "maxJobs": 3,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `prompt` is **required**, must contain Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) prompt.  
  Maximum length 5000 characters.  

- `channel` is optional, if not provided randomly selected available account from [account/midjourney](/docs/api-v2/get-account-midjourney) will be used. See [Setup Midjourney](/docs/start-here/setup-midjourney) for details. Specify the `channel` value when you wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney).  

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 3.  
  This value should be the same or less than your Midjourney subscription plan [Maximum Concurrent Jobs](https://docs.midjourney.com/docs/plans#plan-comparison). Currently, it should be 3 or less for Basic and Standard plans and 15 or less for Pro and Mega plans.  
**Important** Specifying a higher number than supported by your Midjourney subscription will prevent API from functioning properly.  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve job status and results](/docs/api-v2/get-jobs-jobid). `content` contains message generated by Midjourney reflecting current generation parameters and progress.

If you want to retrieve four separate upscaled images once job completed successfully execute [seed_async](/docs/api-v2/post-jobs-seed_async).

```json
{
    "jobid": "<jobid>",
    "verb": "imagine",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "prompt": "Steampunk cat",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "**Steampunk cat --s 750 --v 5.2** - <@Discord user id> (Waiting to start)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "prompt, discord or channel value is missing"
      "prompt, replyRef or replyUrl is too long"
    "code": 400
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**422**
**422 Unprocessable Content**

Moderated message or invalid prompt params, see [Midjourney moderation system](/docs/articles/discord-api-part-2#midjourney-moderation-system).

```json
{
    "error": "Action needed to continue",
    "errorDetails": "Sorry! Our AI moderators feel your prompt might be against our community standards.",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

```json
{
    "error": "Invalid parameter",
    "errorDetails": "Unrecognized parameter(s): `size`",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

**429**
**429 Too Many Requests**

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429.

1. API query is full and can not accept new [jobs/imagine](#midjourney-imagine-command) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). Wait in a loop for **at least** 10..30 seconds and retry again.
```json
{
    "error": "Maximum of <maxJobs> jobs executing in parallel supported",
    "executingJobs": [
      "<jobid>",
      "<jobid>",
      "<jobid>"
    ],
    "code": 429
}
```
1. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response.
```json
{
    "error": "Discord /interactions failed with HTTP status 429",
    "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
    "code": 429
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**503**
**503 Service Unavailable**

During peak load times, the Discord Midjourney bot on rare occasions responds with the message `Failed to process your command :c`. You can safely resubmit the same request again.

```json
{
    "jobid": "<jobid>",
    "verb": "imagine",
    "status": "failed",
    "error": "Discord Agent Status 503",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "prompt": "<prompt>",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "content": "Failed to process your command :c",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 503
}
```

**504**
**504 Job queued**

Job queued. The API will not be able to track the progress of this job, although it will still be processed by Midjourney. You may want to adjust the `maxJobs` number to a lower value for the next several minutes.  

You should not receive this error under normal circumstances unless you have specified a `maxJobs` parameter higher than your Midjourney subscription supports, or if you are using the Midjourney bot outside of API interactions. On occasions when Midjourney is releasing new updates or experiencing technical issues, jobs may be paused for an extended period of time. Our API will mark all jobs running over 30 minutes as `failed`. When Midjourney comes back online, it will attempt to complete previously paused jobs, and you may encounter a conflict if you try to submit a new job at the same time. Although this happens very rarely, we have decided to add an extra layer to ensure such cases are detected. 

```json
{
    "error": "Job queued",
    "jobid": "<jobid>",
    "status": "failed",
    "code": 504
}
```

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "imagine",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "prompt": "Steampunk cat",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'imagine',
  status: 'started' | 'moderated' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  prompt: string,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/imagine \
     -d '{"prompt": "…", "channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/imagine"; 
const token = "API token";
const prompt = "Midjourney prompt";      
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt, channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/imagine" 
token = "API token"
prompt = "Midjourney prompt"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}", 
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-info ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-info
## Midjourney [/info](https://docs.midjourney.com/docs/info) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/info](https://docs.midjourney.com/docs/info) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/info**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional **if only one** Midjourney account configured under [account/midjourney](/docs/api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](/docs/api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "info",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "**User ID**: <user id>\n**Subscription**: Mega (Active monthly, renews next on <t:1705181223>)\n**Visibility Mode**: Public\n**Fast Time Remaining**: 60.0/60.0 hours (100%)\n**Lifetime Usage**: 11170 images (120.63 hours)\n**Relaxed Usage**: 344 images (3.47 hours)\n\n**Queued Jobs (fast)**: 0\n**Queued Jobs (relax)**: 0\n**Running Jobs**: None",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "embeds": [
        {
            "type": "rich",
            "title": "Your info - <Discord name>",
            "description": "**User ID**: <user id>\n**Subscription**: Mega (Active monthly, renews next on <t:1705181223>)\n**Visibility Mode**: Public\n**Fast Time Remaining**: 60.0/60.0 hours (100%)\n**Lifetime Usage**: 11170 images (120.63 hours)\n**Relaxed Usage**: 344 images (3.47 hours)\n\n**Queued Jobs (fast)**: 0\n**Queued Jobs (relax)**: 0\n**Running Jobs**: None",
            "content_scan_version": 0,
            "color": 0
        }
    ],    
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "info",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'info',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, 
  embeds: [
      {
          type: string,
          description: string,
          image: {
              url: string,
              proxy_url: string,
              width: number,
              height: number
          }
      }
  ], 
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/info \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/info"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/info" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-relax ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-relax
## Midjourney [/relax](https://docs.midjourney.com/docs/fast-relax) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/relax](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/relax**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional **if only one** Midjourney account configured under [account/midjourney](/docs/api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](/docs/api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "relax",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "Done! Your jobs now do not consume fast-hours, but might take a little longer. You can always switch back with `/fast`",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "relax",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'relax',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string,
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/relax \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/relax"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/relax" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-remix ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-remix
## Midjourney [/prefer remix](https://docs.midjourney.com/docs/remix) command to toggle remix mode on/off. 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/prefer remix](https://docs.midjourney.com/docs/remix) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/remix**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional, if not provided randomly selected available account from [account/midjourney](/docs/api-v2/get-account-midjourney) will be used. See [Setup Midjourney](/docs/start-here/setup-midjourney) for details. Specify the `channel` value when you wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney).  

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "remix",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "Remix mode turned on! Clicking the variation buttons will now give you a chance to edit your prompt! You can always turn this off by running `/prefer remix` again.",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "remix",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'remix',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string,
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/remix \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/remix"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/remix" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-seed ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-seed
## Retrieve the [seed](https://docs.midjourney.com/docs/seeds).<span class="required-input-field"><b>*</b></span> 
<small>December 2023 (May 5, 2025)</small>

---
<span class="required-input-field"><b>This endpoint will be deprecated on November 1, 2024.</b></span>  
> Starting November 1, 2024 all requests to [jobs/seed](/docs/api-v2/post-jobs-seed) will be routed to [jobs/seed_async](/docs/api-v2/post-jobs-seed_async).  
> Please consider switching to [jobs/seed_async](/docs/api-v2/post-jobs-seed_async) before deadline.

Retrieve the [seed](https://docs.midjourney.com/docs/seeds) and **four separate upscaled** images for the following completed jobs: 
* [jobs/imagine](/docs/api-v2/post-jobs-imagine)
* [jobs/button](/docs/api-v2/post-jobs-button)
* [jobs/blend](/docs/api-v2/post-jobs-blend)
> **https://api.useapi.net/v2/jobs/seed**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "jobid": "jobid",
    "discord": "Discord token",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `jobid` is **required**, `jobid` of successfully completed (`status` set to [*completed*](/docs/api-v2/get-jobs-jobid#model)) [jobs/imagine](/docs/api-v2/post-jobs-imagine), [jobs/button](/docs/api-v2/post-jobs-button) or [jobs/blend](/docs/api-v2/post-jobs-blend) job. 

- `discord` is optional, if provided will override `discord` value of referenced above `jobid`, see [Setup Midjourney](/docs/start-here/setup-midjourney) for details. If the `channel` corresponding to the `jobid` mentioned above has an account configured under [account/midjourney](/docs/api-v2/get-account-midjourney), the current account's `discord` value will be used if it is not explicitly provided. This ensures that even jobs executed some time ago can still be successfully executed by this endpoint, even after possible changes to the account's `discord` value.

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Four separate upscaled images located in `attachments` array.

```json
{
    "jobid": "<jobid>",
    "verb": "seed",
    "status": "completed",
    "created": "2023-09-09T20:19:57.073Z",
    "updated": "2023-09-09T20:19:58.536Z",
    "parentJobId": "<jobid>",
    "seed": {
        "content": "**<prompt>**\n**Job ID**: <Job ID>n**seed** <seed>",
        "value": 123456789
    },    
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "content": "<Discord message content>",
    "attachments": [
       {
           "id": "<id 1>",
           "url": "<image 1 url>",
           "proxy_url": "<image 1 proxy url>",
           "width": 1024,
           "height": 1024,
           "size": 12345,
           "placeholder_version": 1,
           "placeholder": "<placeholder 1>",
           "filename": "<image 1 file name>",
            "content_type": "<image 1 content-type>"
        },
        {
           "id": "<id 2> …the rest of JSON object omitted for brevity…",
        },
        {
           "id": "<id 3> …the rest of JSON object omitted for brevity…",
        },
        {
           "id": "<id 4> …the rest of JSON object omitted for brevity…",
        }
    ],
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T20:19:57.926000+00:00",
    "code": 200
}
```

If the `seed` was already retrieved for the provided `jobid` API will return the original job along with the seed as shown below.

```json
{
    "jobid": "<jobid>",
    "verb": "imagine|button|blend",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "content": "**Steampunk cat --s 750 --v 5.2** - <@Discord user id> (Waiting to start)",
    "attachments": [
       {
          "id": "<id>",
          "url": "<image url>",
          "proxy_url": "<original image proxy url>",
          "width": 2048,
          "height": 2048,
          "size": 1234567,
          "placeholder_version": 1,
          "placeholder": "<placeholder>",
          "filename": "<image file name>",
          "content_type": "<image content-type>"
       }
    ],    
    "seed": {
        "content": "**<prompt>**\n**Job ID**: <Job ID>n**seed** <seed>",
        "value": 123456789
    }, 
    "prompt": "Steampunk cat",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
    "error": 
      "<jobid> is missing"
      "<replyRef | replyUrl> is too long"
      "Parent job must be completed"
      "Job of type <verb> not supported"
      "<discord | channel> is missing"
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**
**404 Not Found**
```json
{
    "error": "Unable to locate parent job <jobid>",
    "code": 404
}
```

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "seed",
    "parentJobId": "<jobid>",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and reset the /account pendingModMessage before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  parentJobId: string,
  verb: 'seed' | 'imagine' | 'button' | 'blend',
  status: 'completed' | 'failed',
  seed: { 
    value: number, // Parsed seed number
    content: string // Original content message returned by Midjourney for a seed request
  },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  attachments: {
    id: string,
    url: string,
    proxy_url: string,
    width: number,
    height: number,
    size: number,
    placeholder_version: number,
    placeholder: string,
    filename: string,
    content_type: string}[], 
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/seed \
     -d '{"jobid": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/seed"; 
const token = "API token";
const jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ jobid });
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/seed" 
token = "API token"
jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "jobid": f"{jobid}", 
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-seed_async ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-seed_async
## Retrieve the [seed](https://docs.midjourney.com/docs/seeds).
<small>October 7, 2024 (August 15, 2025)</small>

---

Retrieve the [seed](https://docs.midjourney.com/docs/seeds) and **four separate upscaled** images for the following completed jobs: 
* [jobs/imagine](/docs/api-v2/post-jobs-imagine)
* [jobs/button](/docs/api-v2/post-jobs-button)
* [jobs/blend](/docs/api-v2/post-jobs-blend)

Please note that video generation jobs are not supported.
> **https://api.useapi.net/v2/jobs/seed_async**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "jobid": "jobid",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `jobid` is **required**, `jobid` of successfully completed (`status` set to [*completed*](/docs/api-v2/get-jobs-jobid#model)) [jobs/imagine](/docs/api-v2/post-jobs-imagine), [jobs/button](/docs/api-v2/post-jobs-button) or [jobs/blend](/docs/api-v2/post-jobs-blend) job. 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

Use returned `jobid` to [retrieve job status and results](/docs/api-v2/get-jobs-jobid). 

If you specify the optional parameter [`replyUrl`](#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails.

```json
{
    "jobid": "<jobid>",
    "verb": "seed_async",
    "status": "started",
    "created": "2023-09-09T20:19:57.073Z",
    "updated": "2023-09-09T20:19:58.536Z",
    "parentJobId": "<jobid>",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
}
```

If the `seed` was already retrieved for the provided `jobid` API will return the original job along with the seed as shown below. You can extract seed value  from field `seed.value` and generated images from  `seed.attachments` array.

```json
{
    "jobid": "<jobid>",
    "verb": "imagine|button|blend",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "content": "**Steampunk cat --s 750 --v 5.2** - <@Discord user id> (fast)",
    "attachments": [
       {
          "id": "<id>",
          "url": "<image url>",
          "proxy_url": "<original image proxy url>",
          "width": 2048,
          "height": 2048,
          "size": 1234567,
          "placeholder_version": 1,
          "placeholder": "<placeholder>",
          "filename": "<image file name>",
          "content_type": "<image content-type>"
       }
    ],    
    "seed": {
        "content": "**<prompt>**\n**Job ID**: <Job ID>n**seed** <seed>",
        "value": 123456789,
        "attachments": [
          {
              "id": "<id 1>",
              "url": "<image 1 url>",
              "proxy_url": "<image 1 proxy url>",
              "width": 1024,
              "height": 1024,
              "size": 12345,
              "placeholder_version": 1,
              "placeholder": "<placeholder 1>",
              "filename": "<image 1 file name>",
                "content_type": "<image 1 content-type>"
            },
            {
              "id": "<id 2> …the rest of JSON object omitted for brevity…",
            },
            {
              "id": "<id 3> …the rest of JSON object omitted for brevity…",
            },
            {
              "id": "<id 4> …the rest of JSON object omitted for brevity…",
            }
        ]
    }, 
    "prompt": "Steampunk cat",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "maxJobs": 3,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
    "error": 
      "<jobid> is missing"
      "<replyRef | replyUrl> is too long"
      "Parent job must be completed"
      "Job of type <verb> not supported"
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**404**
**404 Not Found**
```json
{
    "error": "Unable to locate parent job <jobid>",
    "code": 404
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "seed_async",
    "parentJobId": "<jobid>",
    "status": "failed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and reset the /account pendingModMessage before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  parentJobId: string,
  verb: 'seed_async' | 'imagine' | 'button' | 'blend',
  status: 'started' | 'failed',
  seed: { 
    value: number, // Parsed seed number
    content: string // Original content message returned by Midjourney for a seed request
    attachments: { // Seed images
      id: string,
      url: string,
      proxy_url: string,
      width: number,
      height: number,
      size: number,
      placeholder_version: number,
      placeholder: string,
      filename: string,
      content_type: string}[],
  },
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by Midjourney reflecting current generation parameters and progress
  attachments: {
    id: string,
    url: string,
    proxy_url: string,
    width: number,
    height: number,
    size: number,
    placeholder_version: number,
    placeholder: string,
    filename: string,
    content_type: string}[], 
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/seed_async \
     -d '{"jobid": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/seed_async"; 
const token = "API token";
const jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ jobid });
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/seed_async" 
token = "API token"
jobid = "Completed jobs/imagine, jobs/button or jobs/blend jobid"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "jobid": f"{jobid}", 
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-turbo ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-turbo
## Midjourney [/turbo](https://docs.midjourney.com/docs/fast-relax) command 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/turbo](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/turbo**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional **if only one** Midjourney account configured under [account/midjourney](/docs/api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](/docs/api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "turbo",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "Done! Note that once you exhaust your fast hours, you can purchase more on the website: <https://midjourney.com/account>. To conserve your fast hours, use `/relax` to switch back to relax mode.",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "turbo",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'turbo',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string,
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/turbo \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/turbo"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/turbo" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/post-jobs-variability ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-variability
## Midjourney [/prefer variability](https://docs.midjourney.com/docs/variations) command to toggle between <small>`Vary (Strong)`</small> and <small>`Vary (Subtle)`</small> 
<small>December 2023 (August 15, 2025)</small>

---

Use this endpoint to submit the Midjourney [/prefer variability](https://docs.midjourney.com/docs/variations) command to your [Discord Midjourney channel](/docs/start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 
> **https://api.useapi.net/v2/jobs/variability**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `channel` is optional **if only one** Midjourney account configured under [account/midjourney](/docs/api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](/docs/api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](/docs/api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used.  
  Place here your callback URL. API will call the provided `replyUrl` once job completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-v2/get-jobs-jobid) response.

 - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result.  
  Maximum length 1024 characters.  
  
##### Responses 

**200**

**200 OK**

```json
{
    "jobid": "<jobid>",
    "verb": "variability",
    "status": "completed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:52.774000+00:00",
    "content": "High variability mode turned off! You can always turn this on by running `/prefer variability` again.",
    "code": 200
}
```

**400**
**400 Bad Request**

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```

**401**
**401 Unauthorized**

```json
{
    "error": "Unauthorized",
    "code": 401
}
```

**402**
**402 Payment Required**

```json
{
    "error": "Account has no subscription or subscription expired",
    "code": 402
}
```

**502**
**502 Bad Gateway**

Response code `502` means the Midjourney Discord bot did not reply within the allotted time limit. This usually happens when the [Discord Gateway API](https://discord.com/developers/docs/events/gateway) or the [Midjourney Discord bot](https://discord.com/discovery/applications/936929561302675456) is having issues.   
You can check Discord [status](https://discordstatus.com) and Midjourney Discord server status [channel](https://discord.com/channels/662267976984297473/942231458918064148).   
Keep in mind that both links above most often will not reflect an event that has just started.

**596**
**596 Pending mod message**

API detected Midjourney pending moderation message and CAPTCHA account verification requests. All API calls will be halted and returned 569 response status code until you clear this field by posting to [account/midjourney/`channel`/reset](/docs/api-v2/post-account-midjourney-channel-reset). We will also send you an email when this error ocurred. The best course of action is to log into your Discord account and acknowledge the Midjourney moderation message to prevent a potential ban on your Midjourney account.

```json
{
    "jobid": "<jobid>",
    "verb": "variability",
    "status": "failed",
    "created": "2023-09-09T02:04:52.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "discord": "<ABC…secured…xyz>",
    "channel": "<Discord channel id>",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "error": "Pending mod message",
    "errorDetails": "You have a pending moderation message. Please acknowledge it before using the bot further.",
    "code": 596
}
```

```json
{
    "error": "Your Discord account has received a pending moderation message from Midjourney. Please address this issue and POST account/midjourney/<channel>/reset before making any new API calls.",
    "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, 
  verb: 'variability',
  status: 'completed' | 'failed',
  created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  channel: string,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string,
  timestamp: string,
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v2/jobs/variability \
     -d '{"channel": "…"}'
```

**JavaScript**
``` javascript
const apiUrl = "https://api.useapi.net/v2/jobs/variability"; 
const token = "API token";
const channel = "Discord channel id";      
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  channel 
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
apiUrl = "https://api.useapi.net/v2/jobs/variability" 
token = "API token"
channel = "Discord channel id"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "channel": f"{channel}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-v2/setup-multiple-midjourney-accounts ===
Document URL: https://useapi.net/docs/api-v2/setup-multiple-midjourney-accounts
## How to use multiple Midjourney accounts 
<small>December 2023 (August 15, 2025)</small>

You may configure as many Discord/Midjourney accounts as desired. If more than one account is configured under [account/midjourney](/docs/api-v2/get-account-midjourney), the API will retrieve a list of available accounts, determine which have the capacity to execute the job, and randomly select an available account, thereby effectively acting as a load balancer.

To take advantage of saved configurations and account load balancing, please follow these simple steps:
- Gather your Midjourney account(s) information as outlined at [Setup Midjourney](/docs/start-here/setup-midjourney).
- Post your configuration(s) using the [account/midjourney](/docs/api-v2/post-account-midjourney) endpoint.

To see all your currently configured Midjourney accounts, please use the [account/midjourney](/docs/api-v2/get-account-midjourney) endpoint.

##### Wait there's more…

What if you want to use multiple Midjourney accounts but prefer to implement your own tracking and load balancing logic? Good news – that's still possible! Just continue to providing the `channel` and `maxJobs` values with each call, and our API will take care of the rest, ensuring proper operation. This is possible because API v2 tracks job executions under the same  `channel`. The downside of this approach is that it now becomes your responsibility to determine which account (`channel`) should be used for the next call. However, we suppose this might be precisely what you want in certain situations, so we've kept this option available.

Feel free to [reach out to us](/docs/support) if you have any questions or concerns.

=== URL: https://useapi.net/docs/api-v2/vary-region-mask-editor ===
Document URL: https://useapi.net/docs/api-v2/vary-region-mask-editor
## Simple Vary Region (inpaint) mask editor
<small>November 22, 2024 (February 19, 2026)</small>

Midjourney inpainting [Vary Region](https://docs.midjourney.com/docs/vary-region) and [Vary Region + Remix](https://docs.midjourney.com/docs/vary-region-remix) button require a base64-encoded black and white WebP mask image. The generated base64 mask value is used by the [POST jobs/button](/docs/api-v2/post-jobs-button#request-body) button `Vary (Region)` param `mask`.

{% raw %}

<style>
    #canvasContainer {
        position: relative;
        max-width: 100vw;
        max-height: 100vh;
        /* overflow: hidden; */
        margin: 0 auto;
    }
    #imageCanvas, #maskCanvas {
        display: block;
    }
    #imageCanvas {
        border: 1px solid #ccc;
    }
    #maskCanvas {
        position: absolute;
        left: 0;
        top: 0;
        cursor: crosshair;
    }
    #maskBase64 {
        width: 100%;
        height: 100px;
        margin-top: 10px;
    }
    #copyMaskButton {
        margin-top: 10px;
    }
</style>

<input type="file" id="imageLoader" name="imageLoader"/>
<div id="canvasContainer">
    <canvas id="imageCanvas"></canvas>
    <canvas id="maskCanvas"></canvas>
</div>
<button id="copyMaskButton">Copy Base64 to Clipboard</button>
<textarea id="maskBase64" readonly></textarea>

<script>
    function getMousePos(canvas, evt) {
        var rect = canvas.getBoundingClientRect();
        var scaleX = canvas.width / rect.width;
        var scaleY = canvas.height / rect.height;
        return {
            x: (evt.clientX - rect.left) * scaleX,
            y: (evt.clientY - rect.top) * scaleY
        }
    }

    document.addEventListener('DOMContentLoaded', () => {
        var isDrawing = false;
        var rect = {};
        var img = new Image();
        var base64Mask = ''; 

        var imageLoader = document.getElementById('imageLoader');
        var canvasContainer = document.getElementById('canvasContainer'); 
        var copyMaskButton = document.getElementById('copyMaskButton');
        var maskBase64 = document.getElementById('maskBase64');
        var imageCanvas = document.getElementById('imageCanvas');
        var maskCanvas = document.getElementById('maskCanvas');
        var imageCtx = imageCanvas.getContext('2d');
        var maskCtx = maskCanvas.getContext('2d');

        var viewportWidth = window.innerWidth;
        var rectCanvasContainer = canvasContainer.getBoundingClientRect();
        var viewportHeight = window.innerHeight - rectCanvasContainer.top + window.scrollY;
        
        imageLoader.addEventListener('change', function(e) {
            var reader = new FileReader();
            reader.onload = function(event) {
                img.onload = function() {
                    var widthScale = viewportWidth / img.width;
                    var heightScale = viewportHeight / img.height;
                    var scale = Math.min(widthScale, heightScale, 1);        
                    var scaledWidth = img.width * scale;
                    var scaledHeight = img.height * scale;

                    imageCanvas.width = img.width;
                    imageCanvas.height = img.height;
                    maskCanvas.width = img.width;
                    maskCanvas.height = img.height;

                    imageCanvas.style.width = scaledWidth + 'px';
                    imageCanvas.style.height = scaledHeight + 'px';
                    maskCanvas.style.width = scaledWidth + 'px';
                    maskCanvas.style.height = scaledHeight + 'px';

                    imageCtx.drawImage(img, 0, 0);
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);

                    maskBase64.value = '';
                    base64Mask = '';

                    isDrawing = false;
                    rect = {};
                };
                
                img.src = event.target.result;

            };

            reader.readAsDataURL(e.target.files[0]);

        }, false);

        maskCanvas.addEventListener('mousedown', function(e) {
            isDrawing = true;
            rect = {};
            var pos = getMousePos(maskCanvas, e);
            rect.startX = pos.x;
            rect.startY = pos.y;
            rect.w = 0;
            rect.h = 0;
            maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
        });

        maskCanvas.addEventListener('mousemove', function(e) {
            if (isDrawing) {
                var pos = getMousePos(maskCanvas, e);
                rect.w = pos.x - rect.startX;
                rect.h = pos.y - rect.startY;
                maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                maskCtx.strokeStyle = 'red';
                maskCtx.lineWidth = 2;
                maskCtx.strokeRect(rect.startX, rect.startY, rect.w, rect.h);
            }
        });

        maskCanvas.addEventListener('mouseup', function(e) {
            if (isDrawing) {
                isDrawing = false;
                var rectWidth = Math.abs(rect.w);
                var rectHeight = Math.abs(rect.h);

                if (rectWidth > 1 && rectHeight > 1) {
                    var maskImage = document.createElement('canvas');
                    maskImage.width = maskCanvas.width;
                    maskImage.height = maskCanvas.height;
                    var maskImageCtx = maskImage.getContext('2d');
                    maskImageCtx.fillStyle = '#000';
                    maskImageCtx.fillRect(0, 0, maskImage.width, maskImage.height);
                    var drawX = rect.w >= 0 ? rect.startX : rect.startX + rect.w;
                    var drawY = rect.h >= 0 ? rect.startY : rect.startY + rect.h;
                    maskImageCtx.fillStyle = '#fff';
                    maskImageCtx.fillRect(drawX, drawY, rectWidth, rectHeight);
                    var base64String = maskImage.toDataURL('image/webp');
                    base64Mask = base64String.replace(/^data:image\/webp;base64,/, '');
                    maskBase64.value = base64Mask;
                } else {
                    maskBase64.value = '';
                    base64Mask = '';
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                }
            }
        });

        copyMaskButton.addEventListener('click', function() {
            if (base64Mask) {
                maskBase64.select();
                maskBase64.setSelectionRange(0, maskBase64.value.length);
                try {
                    var successful = document.execCommand('copy');
                    if (successful) {
                        alert('✅ Base64 mask copied to clipboard!');
                    } else {
                        alert('🛑 Failed to copy base64 mask.');
                    }
                } catch (err) {
                    alert('🛑 Oops, unable to copy');
                }
            } else {
                alert('🛑 No base64 mask to copy. Please select a valid rectangle.');
            }
        });
    });
</script>

{% endraw %}

<details markdown="block">

<summary><small>Source code</small></summary>

Copy the code provided below into a `<select desired file name>.html` and open it in your browser.

```html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Simple Vary Region (inpaint) mask editor</title>

<style>
    #canvasContainer {
        position: relative;
        max-width: 100vw;
        max-height: 100vh;
        /* overflow: hidden; */
        margin: 0 auto;
    }
    #imageCanvas, #maskCanvas {
        display: block;
    }
    #imageCanvas {
        border: 1px solid #ccc;
    }
    #maskCanvas {
        position: absolute;
        left: 0;
        top: 0;
        cursor: crosshair;
    }
    #maskBase64 {
        width: 100%;
        height: 100px;
        margin-top: 10px;
    }
    #copyMaskButton {
        margin-top: 10px;
    }
</style>

<input type="file" id="imageLoader" name="imageLoader"/>
<div id="canvasContainer">
    <canvas id="imageCanvas"></canvas>
    <canvas id="maskCanvas"></canvas>
</div>
<button id="copyMaskButton">Copy Base64 to Clipboard</button>
<textarea id="maskBase64" readonly></textarea>

<script>
    function getMousePos(canvas, evt) {
        var rect = canvas.getBoundingClientRect();
        var scaleX = canvas.width / rect.width;
        var scaleY = canvas.height / rect.height;
        return {
            x: (evt.clientX - rect.left) * scaleX,
            y: (evt.clientY - rect.top) * scaleY
        }
    }

    document.addEventListener('DOMContentLoaded', () => {
        var isDrawing = false;
        var rect = {};
        var img = new Image();
        var base64Mask = ''; 

        var imageLoader = document.getElementById('imageLoader');
        var canvasContainer = document.getElementById('canvasContainer'); 
        var copyMaskButton = document.getElementById('copyMaskButton');
        var maskBase64 = document.getElementById('maskBase64');
        var imageCanvas = document.getElementById('imageCanvas');
        var maskCanvas = document.getElementById('maskCanvas');
        var imageCtx = imageCanvas.getContext('2d');
        var maskCtx = maskCanvas.getContext('2d');

        var viewportWidth = window.innerWidth;
        var rectCanvasContainer = canvasContainer.getBoundingClientRect();
        var viewportHeight = window.innerHeight - rectCanvasContainer.top + window.scrollY;
        
        imageLoader.addEventListener('change', function(e) {
            var reader = new FileReader();
            reader.onload = function(event) {
                img.onload = function() {
                    var widthScale = viewportWidth / img.width;
                    var heightScale = viewportHeight / img.height;
                    var scale = Math.min(widthScale, heightScale, 1);        
                    var scaledWidth = img.width * scale;
                    var scaledHeight = img.height * scale;

                    imageCanvas.width = img.width;
                    imageCanvas.height = img.height;
                    maskCanvas.width = img.width;
                    maskCanvas.height = img.height;

                    imageCanvas.style.width = scaledWidth + 'px';
                    imageCanvas.style.height = scaledHeight + 'px';
                    maskCanvas.style.width = scaledWidth + 'px';
                    maskCanvas.style.height = scaledHeight + 'px';

                    imageCtx.drawImage(img, 0, 0);
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);

                    maskBase64.value = '';
                    base64Mask = '';

                    isDrawing = false;
                    rect = {};
                };
                
                img.src = event.target.result;

            };

            reader.readAsDataURL(e.target.files[0]);

        }, false);

        maskCanvas.addEventListener('mousedown', function(e) {
            isDrawing = true;
            rect = {};
            var pos = getMousePos(maskCanvas, e);
            rect.startX = pos.x;
            rect.startY = pos.y;
            rect.w = 0;
            rect.h = 0;
            maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
        });

        maskCanvas.addEventListener('mousemove', function(e) {
            if (isDrawing) {
                var pos = getMousePos(maskCanvas, e);
                rect.w = pos.x - rect.startX;
                rect.h = pos.y - rect.startY;
                maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                maskCtx.strokeStyle = 'red';
                maskCtx.lineWidth = 2;
                maskCtx.strokeRect(rect.startX, rect.startY, rect.w, rect.h);
            }
        });

        maskCanvas.addEventListener('mouseup', function(e) {
            if (isDrawing) {
                isDrawing = false;
                var rectWidth = Math.abs(rect.w);
                var rectHeight = Math.abs(rect.h);

                if (rectWidth > 1 && rectHeight > 1) {
                    var maskImage = document.createElement('canvas');
                    maskImage.width = maskCanvas.width;
                    maskImage.height = maskCanvas.height;
                    var maskImageCtx = maskImage.getContext('2d');
                    maskImageCtx.fillStyle = '#000';
                    maskImageCtx.fillRect(0, 0, maskImage.width, maskImage.height);
                    var drawX = rect.w >= 0 ? rect.startX : rect.startX + rect.w;
                    var drawY = rect.h >= 0 ? rect.startY : rect.startY + rect.h;
                    maskImageCtx.fillStyle = '#fff';
                    maskImageCtx.fillRect(drawX, drawY, rectWidth, rectHeight);
                    var base64String = maskImage.toDataURL('image/webp');
                    base64Mask = base64String.replace(/^data:image\/webp;base64,/, '');
                    maskBase64.value = base64Mask;
                } else {
                    maskBase64.value = '';
                    base64Mask = '';
                    maskCtx.clearRect(0, 0, maskCanvas.width, maskCanvas.height);
                }
            }
        });

        copyMaskButton.addEventListener('click', function() {
            if (base64Mask) {
                maskBase64.select();
                maskBase64.setSelectionRange(0, maskBase64.value.length);
                try {
                    var successful = document.execCommand('copy');
                    if (successful) {
                        alert('✅ Base64 mask copied to clipboard!');
                    } else {
                        alert('🛑 Failed to copy base64 mask.');
                    }
                } catch (err) {
                    alert('🛑 Oops, unable to copy');
                }
            } else {
                alert('🛑 No base64 mask to copy. Please select a valid rectangle.');
            }
        });
    });
</script>

</body>
</html>

```

</details>

=== Cross-reference: General Q&A ===
For cross-cutting tips (rate limiting, prompt moderation, common patterns)
see https://useapi.net/assets/aibot/qa.txt

WARNING: Q&A items are general-purpose and may reference deprecated APIs,
sunsetted services, or scenarios not applicable to the API documented above.
Cross-check against this service's endpoint documentation before applying
any Q&A guidance.