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
---
layout: default
title: Setup Dreamina
parent: Start Here
nav_order: 206
---
# <img src="https://useapi.net/assets/images/dreamina-logo.png" style="height:1em;vertical-align: middle;"> Dreamina
{: .no_toc }

<small>February 23, 2026 (April 3, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 10 minutes to complete setup steps.</small>

---

{: .note }
> This is the setup guide for [Dreamina API](../api-dreamina-v1). An active [Dreamina](https://dreamina.capcut.com/) subscription and a [useapi.net subscription](../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). **Seedance 2.0** and **Seedance 2.0 Fast** — the latest and most capable video models — are, as of April 2, 2026, only available in the **CA region**. The US region offers Seedance 1.5 Pro and Seedance 1.0 Mini. Both regions share the same image models.

To use Seedance 2.0, set up your account with `region: "CA"` as described 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 (Seedance 2.0):**

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 correctly before upgrading to the **Advanced plan** which includes more credits and additional features.

### 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](../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="https://useapi.net/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 — Seedance 2.0)</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

An active [Dreamina](https://dreamina.capcut.com/) subscription is required.

**CA region, [Advanced plan](https://dreamina.capcut.com/)** (C$94.90 / ~USD$68/mo, 37,070 credits).

Credit cost: C$0.26 / ~USD$0.19 per 100 credits (C$1 = ~USD$0.72 as of April 3, 2026)

| Model | Credits/sec | USD/sec |
|-------|-------------|---------|
| Seedance 2.0 Fast | 19 cr/s | **$0.036/s** |
| Seedance 2.0 | 23 cr/s | **$0.044/s** |

| Duration | 2.0 Fast (19 cr/s) | USD | 2.0 (23 cr/s) | USD |
|----------|---------------------|-----|----------------|-----|
| 4s | 76 cr | $0.14 | 92 cr | $0.17 |
| 5s | 95 cr | $0.18 | 115 cr | $0.22 |
| 8s | 152 cr | $0.28 | 184 cr | $0.34 |
| 10s | 190 cr | $0.36 | 230 cr | $0.43 |
| 12s | 228 cr | $0.43 | 276 cr | $0.52 |
| 15s | 285 cr | $0.53 | 345 cr | $0.65 |

![](../../assets/images/setup-dreamina-6.jpg)
<small>CA region pricing — prices shown in Canadian Dollars (C$)</small>

### 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](../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`](../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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: Dreamina API v1
nav_order: 400
---
## Delete Account Configuration
{: .no_toc }

<small>February 23, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts) if you want to use it again.

{: .delete }
> **https://api.useapi.net/v1/dreamina/accounts/`account`**

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

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

### Path Parameters

- `account` is **required**.

### Responses

{% tabs v1_delete_dreamina_accounts_response %}

{% tab v1_delete_dreamina_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Account deleted successfully.

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

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

{% endtab %}

{% tab v1_delete_dreamina_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_dreamina_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

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

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_delete_dreamina_accounts_example %}

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

{% tab v1_delete_dreamina_accounts_example 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);
```
{% endtab %}

{% tab v1_delete_dreamina_accounts_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/<code class="language-plaintext highlighter-rouge">assetId</code>
parent: Dreamina API v1
nav_order: 520
---
## Delete Asset
{: .no_toc }

<small>March 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

{: .delete }
> **https://api.useapi.net/v1/dreamina/assets/`assetId`**

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

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

### Path Parameters

- `assetId` is **required**.

### Responses

{% tabs v1_delete_dreamina_assets_assetid_response %}

{% tab v1_delete_dreamina_assets_assetid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Asset deleted successfully.

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

{% endtab %}

{% tab v1_delete_dreamina_assets_assetid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_dreamina_assets_assetid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

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

{% endtabs %}

### Examples

{% tabs v1_delete_dreamina_assets_assetid_example %}

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

{% tab v1_delete_dreamina_assets_assetid_example 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);
```
{% endtab %}

{% tab v1_delete_dreamina_assets_assetid_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Dreamina API v1
nav_order: 810
---
## Cancel Executing Job
{: .no_toc }

<small>February 23, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

{: .delete }
> **https://api.useapi.net/v1/dreamina/scheduler/`jobid`**

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

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

### Path Parameters

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

### Responses

{% tabs v1_delete_dreamina_scheduler_response %}

{% tab v1_delete_dreamina_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Job removed from scheduler.

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

{% endtab %}

{% tab v1_delete_dreamina_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_dreamina_scheduler_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job belongs to a different user.

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_delete_dreamina_scheduler_example %}

{% tab v1_delete_dreamina_scheduler_example 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"
```
{% endtab %}

{% tab v1_delete_dreamina_scheduler_example 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);
```
{% endtab %}

{% tab v1_delete_dreamina_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: Dreamina API v1
nav_order: 350
---
## Get Account Configuration
{: .no_toc }

<small>February 23, 2026 (March 2, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **https://api.useapi.net/v1/dreamina/accounts/`account`**

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

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

### Path Parameters

- `account` is **required**.

### Responses

{% tabs v1_get_dreamina_accounts_account_response %}

{% tab v1_get_dreamina_accounts_account_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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.

{% endtab %}

{% tab v1_get_dreamina_accounts_account_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_dreamina_accounts_account_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

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

{% endtab %}

{% endtabs %}

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

{% tabs v1_get_dreamina_accounts_account_example %}

{% tab v1_get_dreamina_accounts_account_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/accounts/US:user@example.com"
```
{% endtab %}

{% tab v1_get_dreamina_accounts_account_example 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);
```
{% endtab %}

{% tab v1_get_dreamina_accounts_account_example 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'))
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Dreamina API v1
nav_order: 300
---
## List All Configured Accounts
{: .no_toc }

<small>February 23, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all configured Dreamina accounts.

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

{: .get }
> **https://api.useapi.net/v1/dreamina/accounts**

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

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

### Responses

{% tabs v1_get_dreamina_accounts_response %}

{% tab v1_get_dreamina_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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 `{}`.

{% endtab %}

{% tab v1_get_dreamina_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_get_dreamina_accounts_example %}

{% tab v1_get_dreamina_accounts_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/accounts"
```
{% endtab %}

{% tab v1_get_dreamina_accounts_example 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);
```
{% endtab %}

{% tab v1_get_dreamina_accounts_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/<code class="language-plaintext highlighter-rouge">account</code>
parent: Dreamina API v1
nav_order: 510
---
## List Generation History
{: .no_toc }

<small>March 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

{: .get }
> **https://api.useapi.net/v1/dreamina/assets/`account`**

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

- `API token` is **required**, see [Setup useapi.net](../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

{% tabs v1_get_dreamina_assets_account_response %}

{% tab v1_get_dreamina_assets_account_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-images) or as `firstFrameRef` in [POST /videos](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos).
- `assetId` can be used with [DELETE /assets/`assetId`](https://useapi.net/docs/api-dreamina-v1/delete-dreamina-assets-assetid) to remove an asset.
- Videos do not have `assetRef` — only a `videoUrl` for download.

{% endtab %}

{% tab v1_get_dreamina_assets_account_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_dreamina_assets_account_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

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

{% endtabs %}

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

{% tabs v1_get_dreamina_assets_account_example %}

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

{% tab v1_get_dreamina_assets_account_example 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}`);
});
```
{% endtab %}

{% tab v1_get_dreamina_assets_account_example 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')}")
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Dreamina API v1
nav_order: 720
---
## Retrieve Image Job Status
{: .no_toc }

<small>March 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-images) or [POST /images/upscale](https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale). Jobs are retained for 30 days.

{: .get }
> **https://api.useapi.net/v1/dreamina/images/`jobid`**

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

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

### Path Parameters

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

### Responses

{% tabs v1_get_dreamina_images_jobid_response %}

{% tab v1_get_dreamina_images_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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](https://useapi.net/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`).

{% endtab %}

{% tab v1_get_dreamina_images_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_dreamina_images_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

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

{% endtabs %}

### Model

{% tabs v1_get_dreamina_images_jobid_model %}

{% tab v1_get_dreamina_images_jobid_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
}
```

{% endtab %}

{% tab v1_get_dreamina_images_jobid_model 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 |

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_get_dreamina_images_jobid_examples %}

{% tab v1_get_dreamina_images_jobid_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"
```
{% endtab %}

{% tab v1_get_dreamina_images_jobid_examples 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)
```
{% endtab %}

{% tab v1_get_dreamina_images_jobid_examples 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)
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: Dreamina API v1
nav_order: 800
---
## List Executing Jobs
{: .no_toc }

<small>February 23, 2026 (March 2, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all currently executing (in-progress) video and image generation jobs, grouped by account.

{: .get }
> **https://api.useapi.net/v1/dreamina/scheduler**

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

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

### Responses

{% tabs v1_get_dreamina_scheduler_response %}

{% tab v1_get_dreamina_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```

{% endtab %}

{% tab v1_get_dreamina_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_get_dreamina_scheduler_example %}

{% tab v1_get_dreamina_scheduler_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/dreamina/scheduler"
```
{% endtab %}

{% tab v1_get_dreamina_scheduler_example 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`);
}
```
{% endtab %}

{% tab v1_get_dreamina_scheduler_example 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")
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Dreamina API v1
nav_order: 700
---
## Retrieve Job Status
{: .no_toc }

<small>February 23, 2026 (April 2, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/upscale](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-upscale), or [POST /videos/interpolate](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Jobs are retained for 30 days.

{: .get }
> **https://api.useapi.net/v1/dreamina/videos/`jobid`**

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

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

### Path Parameters

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

### Responses

{% tabs v1_get_dreamina_videos_jobid_response %}

{% tab v1_get_dreamina_videos_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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://v3-web.douyinvod.com/...",
    "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`).

{% endtab %}

{% tab v1_get_dreamina_videos_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_dreamina_videos_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

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

{% endtabs %}

### Model

{% tabs v1_get_dreamina_videos_jobid_model %}

{% tab v1_get_dreamina_videos_jobid_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 video URL (MP4)
    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
}
```

{% endtab %}

{% tab v1_get_dreamina_videos_jobid_model 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 |

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_get_dreamina_videos_jobid_examples %}

{% tab v1_get_dreamina_videos_jobid_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
```
{% endtab %}

{% tab v1_get_dreamina_videos_jobid_examples 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)
```
{% endtab %}

{% tab v1_get_dreamina_videos_jobid_examples 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)
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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/index ===
Document URL: https://useapi.net/docs/api-dreamina-v1/index
---
layout: default
title: Dreamina API v1
nav_order: 2100
has_children: true
permalink: /docs/api-dreamina-v1
---

# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/dreamina-logo.png"> Dreamina API v1
<small>February 23, 2026 (April 2, 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` | CA | 4-15s | 720p | Prompt, First/Last Frame, Omni Reference |
| `seedance-2.0-fast` | 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 |

As of April 2, 2026, Seedance 2.0 and 2.0 Fast are only available in the **CA** (Canada) region. See [Setup Dreamina](../../docs/start-here/setup-dreamina) for CA region account setup.

**Image generation models (US and CA regions):**
- `seedream-5.0-lite` — Latest Seedream model, 2K/4K resolution, up to 6 reference images, auto ratio.
- `seedream-4.6` — Latest stable model, 2K/4K resolution, up to 6 reference images, auto ratio.
- `seedream-4.5` — High quality, 2K/4K resolution, up to 6 reference images, auto ratio.
- `seedream-4.1` — 2K/4K resolution, up to 6 reference images, auto ratio.
- `seedream-4.0` — Balanced quality/speed, 2K/4K resolution, up to 6 reference images, auto ratio.
- `nano-banana` — Fast generation, 1K resolution, up to 3 reference images.
- `seedream-3.0` — 1K/2K resolution, max 1 reference image, no auto ratio.

**Video upscale** — 2x super-resolution via [POST /videos/upscale](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale).

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

**CA region, [Advanced plan](https://dreamina.capcut.com/)** (C$94.90 / ~USD$68/mo, 37,070 credits).

Credit cost: C$0.26 / ~USD$0.19 per 100 credits (C$1 = ~USD$0.72 as of April 3, 2026)

| Model | Credits/sec | USD/sec |
|-------|-------------|---------|
| Seedance 2.0 Fast | 19 cr/s | **$0.036/s** |
| Seedance 2.0 | 23 cr/s | **$0.044/s** |

| Duration | 2.0 Fast (19 cr/s) | USD | 2.0 (23 cr/s) | USD |
|----------|---------------------|-----|----------------|-----|
| 4s | 76 cr | $0.14 | 92 cr | $0.17 |
| 5s | 95 cr | $0.18 | 115 cr | $0.22 |
| 8s | 152 cr | $0.28 | 184 cr | $0.34 |
| 10s | 190 cr | $0.36 | 230 cr | $0.43 |
| 12s | 228 cr | $0.43 | 276 cr | $0.52 |
| 15s | 285 cr | $0.53 | 345 cr | $0.65 |

![](../../assets/images/setup-dreamina-6.jpg)
<small>CA region pricing — prices shown in Canadian Dollars (C$)</small>

</details>


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

📦 [Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(April 2, 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, 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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Dreamina API v1
nav_order: 200
---
## Configure Dreamina Account
{: .no_toc }

<small>February 23, 2026 (April 2, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Configure your Dreamina account for API access using email and password credentials. See [Setup Dreamina](../start-here/setup-dreamina) for details.

{: .post }
> **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](../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`. Use `CA` (Canada) for access to Seedance 2.0 models. See [Setup Dreamina](../start-here/setup-dreamina) for region-specific setup.
- `maxJobs` is optional. Maximum concurrent jobs for this account (1-50, default: `10`).
### Responses

{% tabs v1_post_dreamina_accounts_response %}

{% tab v1_post_dreamina_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
  }
}
```

{% endtab %}

{% tab v1_post_dreamina_accounts_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error (missing/invalid parameters).

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

{% tab v1_post_dreamina_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_accounts_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_dreamina_accounts_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

Login failed (bad credentials, upstream error).

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

{% endtabs %}

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

{% tabs v1_post_dreamina_accounts_example %}

{% tab v1_post_dreamina_accounts_example 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"
     }'
```
{% endtab %}

{% tab v1_post_dreamina_accounts_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_accounts_example 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())
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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 — Seedance 2.0)</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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/<code class="language-plaintext highlighter-rouge">account</code>
parent: Dreamina API v1
nav_order: 500
---
## Upload Assets
{: .no_toc }

<small>February 23, 2026 (April 3, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos), and `imageRef_N` in [POST /images](https://useapi.net/docs/api-dreamina-v1/post-dreamina-images).
- **Videos:** `omni_N_videoRef` in [POST /videos](https://useapi.net/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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos) Omni Reference mode (max 3 per request, total duration max 15s).

{: .post }
> **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](../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

{% tabs v1_post_dreamina_assets_response %}

{% tab v1_post_dreamina_assets_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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>`

{% endtab %}

{% tab v1_post_dreamina_assets_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
}
```
{% endtab %}

{% tab v1_post_dreamina_assets_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_assets_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

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

{% tab v1_post_dreamina_assets_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

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

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

{% endtabs %}

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

{% tabs v1_post_dreamina_assets_example %}

{% tab v1_post_dreamina_assets_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_assets_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_assets_example 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'))
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale
parent: Dreamina API v1
nav_order: 730
---
## Upscale Image
{: .no_toc }

<small>March 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

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

{: .post }
> **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](../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](https://useapi.net/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.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

{% tabs v1_post_dreamina_images_upscale_response %}

{% tab v1_post_dreamina_images_upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Upscale job created. Poll [GET /images/`jobid`](https://useapi.net/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
}
```

{% endtab %}

{% tab v1_post_dreamina_images_upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

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

{% tab v1_post_dreamina_images_upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_images_upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Source image job not found.

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

{% endtabs %}

### Examples

{% tabs v1_post_dreamina_images_upscale_example %}

{% tab v1_post_dreamina_images_upscale_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_images_upscale_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_images_upscale_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images
parent: Dreamina API v1
nav_order: 710
---
## Generate Images
{: .no_toc }

<small>March 4, 2026 (April 2, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/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 |

{: .post }
> **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](../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`](https://useapi.net/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.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

{% tabs v1_post_dreamina_images_response %}

{% tab v1_post_dreamina_images_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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`](https://useapi.net/docs/api-dreamina-v1/get-dreamina-images-jobid) for completion status, or use `replyUrl` for webhook callbacks.

{% endtab %}

{% tab v1_post_dreamina_images_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
}
```
{% endtab %}

{% tab v1_post_dreamina_images_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_images_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

All accounts at maximum capacity.

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

{% endtabs %}

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

{% tabs v1_post_dreamina_images_example %}

{% tab v1_post_dreamina_images_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_images_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_images_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/interpolate
parent: Dreamina API v1
nav_order: 706
---
## Interpolate Video
{: .no_toc }

<small>April 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result.

{: .post }
> **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](../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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos) or a completed video upscale job from [POST /videos/upscale](https://useapi.net/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.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

{% tabs v1_post_dreamina_videos_interpolate_response %}

{% tab v1_post_dreamina_videos_interpolate_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Interpolation job created. Poll [GET /videos/`jobid`](https://useapi.net/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
}
```

{% endtab %}

{% tab v1_post_dreamina_videos_interpolate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
}
```
{% endtab %}

{% tab v1_post_dreamina_videos_interpolate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_videos_interpolate_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Source video job not found.

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

{% endtabs %}

### Examples

{% tabs v1_post_dreamina_videos_interpolate_example %}

{% tab v1_post_dreamina_videos_interpolate_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_videos_interpolate_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_videos_interpolate_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale
parent: Dreamina API v1
nav_order: 705
---
## Upscale Video
{: .no_toc }

<small>April 2, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos). Each video can only be upscaled once.

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

{: .post }
> **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](../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](https://useapi.net/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.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.
- `maxJobs` is optional, override max concurrent jobs for this request (1-50).

### Responses

{% tabs v1_post_dreamina_videos_upscale_response %}

{% tab v1_post_dreamina_videos_upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Upscale job created. Poll [GET /videos/`jobid`](https://useapi.net/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
}
```

{% endtab %}

{% tab v1_post_dreamina_videos_upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
}
```
{% endtab %}

{% tab v1_post_dreamina_videos_upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_videos_upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Source video job not found.

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

{% endtabs %}

### Examples

{% tabs v1_post_dreamina_videos_upscale_example %}

{% tab v1_post_dreamina_videos_upscale_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_videos_upscale_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_videos_upscale_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos
parent: Dreamina API v1
nav_order: 600
---
## Generate Videos
{: .no_toc }

<small>February 23, 2026 (April 3, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/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) |

{: .note }
> **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` | CA | 4-15s | 720p | Prompt, First/Last Frame, Omni Reference |
| `seedance-2.0-fast` | 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 |

As of April 3, 2026, Seedance 2.0 and 2.0 Fast are only available in the **CA** (Canada) region. See [Setup Dreamina](../start-here/setup-dreamina) for CA region account setup.

{: .note }
> **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.

{: .post }
> **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](../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` for CA, `seedance-1.5-pro` for US). 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`). Only `seedance-1.5-pro`, `seedance-1.0-mini`, and `seedance-1.0-fast` support `1080p`. Model `seedance-1.0-pro` is always `1080p`.
- `firstFrameRef` is optional, `imageRef` from [POST /assets/`account`](https://useapi.net/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.
- `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`](https://useapi.net/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`](https://useapi.net/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

{% tabs v1_post_dreamina_videos_response %}

{% tab v1_post_dreamina_videos_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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`](https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid) for completion status, or use `replyUrl` for webhook callbacks.

{% endtab %}

{% tab v1_post_dreamina_videos_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% tab v1_post_dreamina_videos_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_dreamina_videos_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_dreamina_videos_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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

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

{% tab v1_post_dreamina_videos_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

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

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

{% endtabs %}

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

{% tabs v1_post_dreamina_videos_example %}

{% tab v1_post_dreamina_videos_example 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"
```
{% endtab %}

{% tab v1_post_dreamina_videos_example 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);
```
{% endtab %}

{% tab v1_post_dreamina_videos_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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 (CA only)</option>
          <option value="seedance-2.0-fast">seedance-2.0-fast (CA only)</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="https://useapi.net/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
---
layout: default
title: Setup InsightFaceSwap
parent: Start Here
nav_order: 500
---
# <img style="height:1.8em;vertical-align: middle;" src="https://useapi.net/assets/images/picsi.png"> Setup InsightFaceSwap 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 3 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [InsightFaceSwap API](../api-faceswap-v1). A [Discord](https://discord.com) account and a [useapi.net subscription](../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`](../api-faceswap-v1/post-faceswap-account-channel) and complete the configuration.

##### Server 
{: .no_toc }

<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
{: .no_toc }

<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
---
layout: default
title: InsightFaceSwap API v1
nav_order: 9000
has_children: true
permalink: /docs/api-faceswap-v1
---

# <img style="height:1.8em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/aiAPI"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: InsightFaceSwap API v1
nav_order: 400
---
## Delete InsightFaceSwap account
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/faceswap/account/`channel`**

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

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

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

##### Responses 

{% tabs del_account_InsightFaceSwap_response %}

{% tab del_account_InsightFaceSwap_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_InsightFaceSwap_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_InsightFaceSwap_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_InsightFaceSwap_example %}

{% tab del_account_InsightFaceSwap_example 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> 
```
{% endtab %}

{% tab del_account_InsightFaceSwap_example 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});
```
{% endtab %}

{% tab del_account_InsightFaceSwap_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/delid
parent: InsightFaceSwap API v1
nav_order: 1100
---
## InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
}
```
- `channel` is optional when only one [faceswap/account](../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](../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 

{% tabs post_faceswap-delid_response %}

{% tab post_faceswap-delid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-delid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-delid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-delid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-delid_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-delid_example %}

{% tab faceswap-delid_example 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>" 
```
{% endtab %}

{% tab faceswap-delid_example 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()
```
{% endtab %}

{% tab faceswap-delid_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: InsightFaceSwap API v1
nav_order: 200
---
## Retrieve InsightFaceSwap configuration for `channel` 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/faceswap/account/`channel`**

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

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

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

##### Responses 

{% tabs get_account_InsightFaceSwap_channel_response %}

{% tab get_account_InsightFaceSwap_channel_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
    }
}
```
{% endtab %}

{% tab get_account_InsightFaceSwap_channel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_InsightFaceSwap_channel_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs get_account_InsightFaceSwap_channel_example %}

{% tab get_account_InsightFaceSwap_channel_example Curl %}
``` bash
curl https://api.useapi.net/v1/faceswap/account/<channel> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_InsightFaceSwap_channel_example 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});
```
{% endtab %}

{% tab get_account_InsightFaceSwap_channel_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/account
parent: InsightFaceSwap API v1
nav_order: 100
---
## Retrieve InsightFaceSwap accounts information
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Before you start using the API, you **must** [configure](../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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_InsightFaceSwap_response %}

{% tab account_InsightFaceSwap_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
        }
    }    
}
```
{% endtab %}

{% tab account_InsightFaceSwap_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_InsightFaceSwap_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs account_InsightFaceSwap_example %}

{% tab account_InsightFaceSwap_example Curl %}
``` bash
curl https://api.useapi.net/v1/faceswap/account \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_InsightFaceSwap_example 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});
```
{% endtab %}

{% tab account_InsightFaceSwap_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: InsightFaceSwap API v1
nav_order: 1300
---

## Retrieve InsightFaceSwap job status and results
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

If you specified optional parameter [`replyUrl`](../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.

{: .get }
> **https://api.useapi.net/v1/faceswap/jobs/?jobid=`jobid`**

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

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

##### Responses 
{:toc}

{% tabs get_faceswap_jobid_response %}

{% tab get_faceswap_jobid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab get_faceswap_jobid_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% tab get_faceswap_jobid_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab get_faceswap_jobid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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


{% tab get_faceswap_jobid_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% tab get_faceswap_jobid_response <span class="http-status-bad">410</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

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

{% endtab %}

{% endtabs %}

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

{% tabs faceswap_jobid_example %}

{% tab faceswap_jobid_example Curl %}
``` bash
curl https://api.useapi.net/v1/faceswap/jobs/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab faceswap_jobid_example 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});
```
{% endtab %}

{% tab faceswap_jobid_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> …/cancel/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: InsightFaceSwap API v1
nav_order: 2000
---

## Cancel InsightFaceSwap job
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Cancel execution of job created by 
- [faceswap/headshot](../api-faceswap-v1/post-faceswap-headshot)
- [faceswap/changebg](../api-faceswap-v1/post-faceswap-changebg)
- [faceswap/picsi](../api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started`

{: .get }
> **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](../start-here/setup-useapi) for details.   

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

##### Responses 
{:toc}

{% tabs post_faceswap_cancel_response %}

{% tab post_faceswap_cancel_response <span class="http-status-good">200</span> %}

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

{% endtab %}

{% tab post_faceswap_cancel_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% endtab %}

{% tab post_faceswap_cancel_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_faceswap_cancel_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}


{% tab post_faceswap_cancel_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs faceswap_cancel_example %}

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

{% tab faceswap_cancel_example 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});
```
{% endtab %}

{% tab faceswap_cancel_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs ===
Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/jobs
parent: InsightFaceSwap API v1
nav_order: 3000
---

## Get list of currently executing InsightFaceSwap jobs
{: .no_toc }
 
## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/faceswap/jobs**

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

##### Responses 
{:toc}

{% tabs post_pika_jobs_response %}

{% tab post_pika_jobs_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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

{% endtab %}

{% tab post_pika_jobs_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_pika_jobs_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs pika_jobs_example %}

{% tab pika_jobs_example Curl %}
``` bash
curl https://api.useapi.net/v1/faceswap/jobs \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab pika_jobs_example 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});
```
{% endtab %}

{% tab pika_jobs_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: InsightFaceSwap API v1
nav_order: 300
---
## Create or update InsightFaceSwap account information
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Before you start using the API, you **must** [configure](../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.

{: .post }
> **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](../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](../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 

{% tabs post_account_InsightFaceSwap_response %}

{% tab post_account_InsightFaceSwap_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab post_account_InsightFaceSwap_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```
{% endtab %}

{% tab post_account_InsightFaceSwap_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_account_InsightFaceSwap_example %}

{% tab post_account_InsightFaceSwap_example 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": …}'
```
{% endtab %}

{% tab post_account_InsightFaceSwap_example 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});
```
{% endtab %}

{% tab post_account_InsightFaceSwap_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/changebg
parent: InsightFaceSwap API v1
nav_order: 470
---
## InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command to your [InsightFaceSwap Discord channel](../start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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](https://useapi.net/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](../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 

{% tabs post_faceswap-changebg_response %}

{% tab post_faceswap-changebg_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve InsightFaceSwap job status and results](../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
}
```
{% endtab %}

{% tab post_faceswap-changebg_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-changebg_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-changebg_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-changebg_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-changebg_example %}

{% tab faceswap-changebg_example 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>" 
```
{% endtab %}

{% tab faceswap-changebg_example 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()

```
{% endtab %}

{% tab faceswap-changebg_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/delall
parent: InsightFaceSwap API v1
nav_order: 1200
---
## InsightFaceSwap [/delall](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delall) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id"
}
```
- `channel` is optional when only one [faceswap/account](../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](../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 

{% tabs post_faceswap-delall_response %}

{% tab post_faceswap-delall_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-delall_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-delall_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-delall_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-delall_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-delall_example %}

{% tab faceswap-delall_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/faceswap/delall \
     -F "channel=<Discord channel id>" 
```
{% endtab %}

{% tab faceswap-delall_example 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()
```
{% endtab %}

{% tab faceswap-delall_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/headshot
parent: InsightFaceSwap API v1
nav_order: 950
---
## InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command to your [InsightFaceSwap Discord channel](../start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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](../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](../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 

{% tabs post_faceswap-headshot_response %}

{% tab post_faceswap-headshot_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve InsightFaceSwap job status and results](../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
}
```
{% endtab %}

{% tab post_faceswap-headshot_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-headshot_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-headshot_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-headshot_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-headshot_example %}

{% tab faceswap-headshot_example 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>" 
```
{% endtab %}

{% tab faceswap-headshot_example 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()

```
{% endtab %}

{% tab faceswap-headshot_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/inswapper
parent: InsightFaceSwap API v1
nav_order: 900
---
## InsightFaceSwap [Apps/INSwapper](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#appsinswapper) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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](https://useapi.net/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.

{: .post }
> **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](../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](../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](../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 

{% tabs post_faceswap-inswapper_response %}

{% tab post_faceswap-inswapper_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-inswapper_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}

{% tab post_faceswap-inswapper_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-inswapper_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-inswapper_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

```json
{
    "error": 
      "Unable to locate message <targetMessageId> is channel <channel>"
      "Unable to locate attachments for message <targetMessageId>"
    "code": 404
}
```
{% endtab %}

{% tab post_faceswap-inswapper_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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](#insightfaceswap-inswapper-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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-inswapper_example %}

{% tab faceswap-inswapper_example 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>" 
```
{% endtab %}

{% tab faceswap-inswapper_example 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()

```
{% endtab %}

{% tab faceswap-inswapper_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/listid
parent: InsightFaceSwap API v1
nav_order: 500
---
## InsightFaceSwap [/listid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#listid) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id"
}
```
- `channel` is optional when only one [faceswap/account](../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](../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 

{% tabs post_faceswap-listid_response %}

{% tab post_faceswap-listid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-listid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-listid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-listid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-listid_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-listid_example %}

{% tab faceswap-listid_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/faceswap/listid \
     -F "channel=<Discord channel id>" 
```
{% endtab %}

{% tab faceswap-listid_example 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()
```
{% endtab %}

{% tab faceswap-listid_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/picsi
parent: InsightFaceSwap API v1
nav_order: 450
---
## InsightFaceSwap [/picsi](https://www.patreon.com/posts/introducing-ai-5-101604168) command 
{: .no_toc }

<small>February 12, 2024 (November 18, 2024)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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.

{: .post }
> **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](../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](https://useapi.net/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](../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 

{% tabs post_faceswap-picsi_response %}

{% tab post_faceswap-picsi_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

If field `status` returned as `started` use returned `jobid` to [retrieve InsightFaceSwap job status and results](../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
}
```
{% endtab %}

{% tab post_faceswap-picsi_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}

{% tab post_faceswap-picsi_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-picsi_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-picsi_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

```json
{
    "error": "Not enough credits: requested 3, available 0",
    "code": 412
}
```
{% endtab %}

{% tab post_faceswap-picsi_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-picsi_example %}

{% tab faceswap-picsi_example 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>"' 
```
{% endtab %}

{% tab faceswap-picsi_example 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()

```
{% endtab %}

{% tab faceswap-picsi_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/saveid
parent: InsightFaceSwap API v1
nav_order: 600
---
## InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .post }
> **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](../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](../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](../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 

{% tabs post_faceswap-saveid_response %}

{% tab post_faceswap-saveid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-saveid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-saveid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-saveid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-saveid_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-saveid_example %}

{% tab faceswap-saveid_example 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>" 
```
{% endtab %}

{% tab faceswap-saveid_example 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()

```
{% endtab %}

{% tab faceswap-saveid_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/setid
parent: InsightFaceSwap API v1
nav_order: 1000
---
## InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "channel": "Discord channel id",
    "idname": "idname param",
}
```
- `channel` is optional when only one [faceswap/account](../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](../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 

{% tabs post_faceswap-setid_response %}

{% tab post_faceswap-setid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-setid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-setid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-setid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-setid_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-setid_example %}

{% tab faceswap-setid_example 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>" 
```
{% endtab %}

{% tab faceswap-setid_example 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()
```
{% endtab %}

{% tab faceswap-setid_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swap ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swap
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/swap
parent: InsightFaceSwap API v1
nav_order: 800
---
## 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.
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---
<span class="required-input-field"><b>As of July 23, 2024 this endpoint is deprecated.</b></span>   
**We suggest using recently added [faceswap/picsi](../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](https://useapi.net/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.

{: .post }
> **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](../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](https://useapi.net/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](../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 

{% tabs post_faceswap-swap_response %}

{% tab post_faceswap-swap_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-swap_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-swap_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-swap_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-swap_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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](#insightfaceswap-swap-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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-swap_example %}

{% tab faceswap-swap_example 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>" 
```
{% endtab %}

{% tab faceswap-swap_example 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()

```
{% endtab %}

{% tab faceswap-swap_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid ===
Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/swapid
parent: InsightFaceSwap API v1
nav_order: 700
---
## InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command 
{: .no_toc }

<small>February 12, 2024 (November 18, 2024)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](https://useapi.net/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.

{: .post }
> **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](../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](../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](../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 

{% tabs post_faceswap-swapid_response %}

{% tab post_faceswap-swapid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab post_faceswap-swapid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```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
}
```
{% endtab %}


{% tab post_faceswap-swapid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_faceswap-swapid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_faceswap-swapid_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

```json
{
    "error": "Not enough credits: requested 3, available 0",
    "code": 412
}
```
{% endtab %}


{% tab post_faceswap-swapid_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs faceswap-swapid_example %}

{% tab faceswap-swapid_example 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>" 
```
{% endtab %}

{% tab faceswap-swapid_example 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()

```
{% endtab %}

{% tab faceswap-swapid_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: ⚙️ Setup multiple accounts
parent: InsightFaceSwap API v1
nav_order: 6000
---
## How to use multiple InsightFaceSwap accounts 
{: .no_toc }

Before you start using the API, you **must** [configure](../start-here/setup-faceswap) at least one InsightFaceSwap Discord [faceswap/account](../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](../start-here/setup-faceswap).
- Post your configuration(s) using the [faceswap/account/`channel`](../api-faceswap-v1/post-faceswap-account-channel) endpoint.

To see all your currently configured InsightFaceSwap accounts, please use the [faceswap/account](../api-faceswap-v1/get-faceswap-account) endpoint.

Feel free to [reach out to us](../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
---
layout: default
title: Setup Google Flow
parent: Start Here
nav_order: 205
---
# <img src="https://useapi.net/assets/images/google-flow.svg" style="height:1em;vertical-align: middle;"> Google Flow
{: .no_toc }

<small>November 17, 2025 (February 11, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 15 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [Google Flow API](../api-google-flow-v1). An active [Google](https://accounts.google.com) account and a [useapi.net subscription](../subscription) are required for the API to work.

[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](../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="https://useapi.net/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](../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](../api-google-flow-v1/post-google-flow-images), [POST /images/upscale](../api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](../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](../api-google-flow-v1/post-google-flow-accounts-captcha-providers)

**Tips:**
- Use [GET /accounts/captcha-stats?anonymized=true](../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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Google Flow API v1
nav_order: 400
---
## Delete Account Configuration
{: .no_toc }

<small>November 17, 2025</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts) if you want to use it again.

{: .delete }
> **https://api.useapi.net/v1/google-flow/accounts/`email`**

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

- `API token` is **required**, see [Setup useapi.net](../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

{% tabs v1_delete_accounts_response %}

{% tab v1_delete_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Account deleted successfully.

```json
{
  "message": "Google Flow account john@gmail.com deleted"
}
```

{% endtab %}

{% tab v1_delete_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_delete_accounts_example %}

{% tab v1_delete_accounts_example Curl %}
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com"
```
{% endtab %}

{% tab v1_delete_accounts_example 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);
```
{% endtab %}

{% tab v1_delete_accounts_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> …/captcha-providers
parent: Google Flow API v1
nav_order: 420
---
## Get Captcha Providers
{: .no_toc }

<small>December 23, 2025 (February 18, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve configured captcha provider API keys (masked for security).

{: .get }
> **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](../start-here/setup-useapi) for details.

### Responses

{% tabs v1_get_captcha_providers_response %}

{% tab v1_get_captcha_providers_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab v1_get_captcha_providers_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_get_captcha_providers_example %}

{% tab v1_get_captcha_providers_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/captcha-providers"
```
{% endtab %}

{% tab v1_get_captcha_providers_example 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);
```
{% endtab %}

{% tab v1_get_captcha_providers_example 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())
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> …/captcha-stats
parent: Google Flow API v1
nav_order: 425
---
## Get Captcha Statistics
{: .no_toc }

<small>February 4, 2026 (February 14, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../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

{% tabs v1_get_captcha_stats_response %}

{% tab v1_get_captcha_stats_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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": 97.50,
      "AntiCaptcha": 96.67,
      "EzCaptcha": 91.67
    },
    "by_status_code_images": {
      "200": 85.71,
      "403": 14.29
    },
    "by_status_code_videos": {
      "200": 94.29,
      "403": 5.71
    },
    "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": "",
      "statusCode": 200,
      "captchaDurationMs": 8500,
      "apiDurationMs": 1200,
      "attemptNumber": 1
    }
  ]
}
```

The `summary` object provides aggregated statistics (omitted if no data).

{% endtab %}

{% tab v1_get_captcha_stats_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Missing or invalid parameters.

```json
{
  "error": "<error message>"
}
```

{% endtab %}

{% tab v1_get_captcha_stats_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

### 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>    // Number of records per provider in the sample (excludes 503)
    success_rate_by_provider: Record<string, number>  // Success rate % per provider (excludes 503)
    by_status_code_images: Record<string, number>     // Status code % for IMAGE actions
    by_status_code_videos: Record<string, number>     // Status code % for VIDEO actions
    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)
    statusCode: number           // HTTP status code (200, 403, 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

{% tabs v1_get_captcha_stats_example %}

{% tab v1_get_captcha_stats_example 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"
```
{% endtab %}

{% tab v1_get_captcha_stats_example 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);
```
{% endtab %}

{% tab v1_get_captcha_stats_example 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
)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Google Flow API v1
nav_order: 350
---
## Get Account Configuration
{: .no_toc }

<small>November 17, 2025 (December 1, 2025)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Get configuration details for a specific Google Flow account, including health status, credits information, and available video models.

{: .get }
> **https://api.useapi.net/v1/google-flow/accounts/`email`**

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

- `API token` is **required**, see [Setup useapi.net](../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

{% tabs v1_get_accounts_email_response %}

{% tab v1_get_accounts_email_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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_fast_ultra",
        "displayName": "Veo 3.1 - Fast",
        "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE"],
        "capabilities": ["VIDEO_MODEL_CAPABILITY_TEXT", "VIDEO_MODEL_CAPABILITY_AUDIO"],
        "videoLengthSeconds": 8,
        "videoGenerationTimeSeconds": 100,
        "framesPerSecond": 24,
        "paygateTier": "PAYGATE_TIER_TWO",
        "accessType": "MODEL_ACCESS_TYPE_GENERAL",
        "modelAccessInfo": {},
        "modelMetadata": {
          "veoModelName": "Beta Audio"
        }
      },
      {
        "key": "veo_3_1_t2v",
        "displayName": "Veo 3.1 - Quality",
        "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE"],
        "capabilities": ["VIDEO_MODEL_CAPABILITY_TEXT", "VIDEO_MODEL_CAPABILITY_AUDIO"],
        "videoLengthSeconds": 8,
        "videoGenerationTimeSeconds": 210,
        "creditCost": 100,
        "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"`.

**Ultra Plan Models:** For accounts with Google AI Ultra subscription ([PAYGATE_TIER_TWO](https://one.google.com/ai)), video models with keys ending in `_ultra` do not include a `creditCost` field, indicating unlimited generation for these models.

{% endtab %}

{% tab v1_get_accounts_email_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_accounts_email_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Google Flow account email@example.com not found"
}
```

{% endtab %}

{% endtabs %}

### 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"
      supportedAspectRatios: string[]
      capabilities: string[]   // e.g., ["VIDEO_MODEL_CAPABILITY_TEXT", "VIDEO_MODEL_CAPABILITY_AUDIO"]
      videoLengthSeconds: number
      videoGenerationTimeSeconds?: number
      creditCost?: number      // Absent for unlimited Ultra models (keys ending in _ultra)
      framesPerSecond: number
      paygateTier: string      // "PAYGATE_TIER_ONE" | "PAYGATE_TIER_TWO"
      accessType: string
      modelAccessInfo: object
      modelMetadata: object
    }>
  }
  error?: string               // Error message
}
```

### Examples

{% tabs v1_get_accounts_email_example %}

{% tab v1_get_accounts_email_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com"
```
{% endtab %}

{% tab v1_get_accounts_email_example 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);
```
{% endtab %}

{% tab v1_get_accounts_email_example 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'))
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Google Flow API v1
nav_order: 300
---
## List All Configured Accounts
{: .no_toc }

<small>November 17, 2025 (December 1, 2025)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all configured Google Flow accounts.

To get a specific account use [GET /accounts/`email`](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-email).

{: .get }
> **https://api.useapi.net/v1/google-flow/accounts**

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

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

### Responses

{% tabs v1_get_accounts_response %}

{% tab v1_get_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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 `{}`.

{% endtab %}

{% tab v1_get_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_get_accounts_example %}

{% tab v1_get_accounts_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/google-flow/accounts"
```
{% endtab %}

{% tab v1_get_accounts_example 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);
```
{% endtab %}

{% tab v1_get_accounts_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Google Flow API v1
nav_order: 800
---
## Retrieve Job Status
{: .no_toc }

<small>November 17, 2025 (February 14, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos#async-mode) 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](https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs).

{: .get }
> **https://api.useapi.net/v1/google-flow/jobs/`jobId`**

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

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

### Path Parameters

- `jobId` is **required**, the unique job identifier returned from [POST /images](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images) or [POST /videos](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos).

### Responses

{% tabs v1_get_jobs_jobid_response %}

{% tab v1_get_jobs_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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"
    }
  }
}
```

{% endtab %}

{% tab v1_get_jobs_jobid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid job ID format.

```json
{
  "error": "Invalid job ID format"
}
```
{% endtab %}

{% tab v1_get_jobs_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_jobs_jobid_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

Job belongs to a different user.

```json
{
  "error": "Access denied - job belongs to different user"
}
```
{% endtab %}

{% tab v1_get_jobs_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found in database.

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

{% tab v1_get_jobs_jobid_response <span class="http-status-bad">410</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

Job has expired (jobs are retained for 7 days).

```json
{
  "error": "Job has expired"
}
```
{% endtab %}

{% endtabs %}

### Model

{% tabs v1_get_jobs_jobid_model %}

{% tab v1_get_jobs_jobid_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'
    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)
}
```

{% endtab %}

{% tab v1_get_jobs_jobid_model 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)
}
```

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_get_jobs_jobid_examples %}

{% tab v1_get_jobs_jobid_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
```
{% endtab %}

{% tab v1_get_jobs_jobid_examples 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)
```
{% endtab %}

{% tab v1_get_jobs_jobid_examples 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']}")
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs
parent: Google Flow API v1
nav_order: 810
---
## Get Load Balancing Statistics
{: .no_toc }

<small>November 17, 2025 (November 19, 2025)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs-jobid).

{: .get }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images) or [POST /videos](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos), the API automatically selects the best account using a scoring algorithm:

**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

{% tabs v1_get_jobs_response %}

{% tab v1_get_jobs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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": { "..." }
  }
}
```

{% endtab %}

{% tab v1_get_jobs_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid `options` parameter value.

```json
{
  "error": "Invalid options parameter. Use: summary, executing, or history"
}
```
{% endtab %}

{% tab v1_get_jobs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_get_jobs_examples %}

{% tab v1_get_jobs_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}"
```
{% endtab %}

{% tab v1_get_jobs_examples 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)
```
{% endtab %}

{% tab v1_get_jobs_examples 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', {}))}")
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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/index ===
Document URL: https://useapi.net/docs/api-google-flow-v1/index
---
layout: default
title: Google Flow API v1
nav_order: 2000
has_children: true
permalink: /docs/api-google-flow-v1
---

# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/google-flow.svg"> Google Flow API v1
<small>November 17, 2025 (April 3, 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 Fast Relaxed` — free, Ultra only (lower priority)
- **Voice narration** — 30 AI voice presets for spoken dialogue (works with R2V mode)

Official Google AI Pro and Google AI Ultra [credits table](https://support.google.com/googleone/answer/16287445).

**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>(April 3, 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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/GoogleFlowAPI/"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/captcha-providers
parent: Google Flow API v1
nav_order: 410
---
## Configure Captcha Providers
{: .no_toc }

<small>December 23, 2025 (February 18, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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
{: .no_toc }

These parameters are available on all endpoints that require captcha: [POST /images](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale), [POST /videos](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos), [POST /videos/upscale](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-upscale), [POST /videos/extend](https://useapi.net/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.

{: .post }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos)

### Responses

{% tabs v1_post_captcha_providers_response %}

{% tab v1_post_captcha_providers_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```
{% endtab %}

{% tab v1_post_captcha_providers_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid provider name specified.

```json
{
  "error": "Invalid captcha provider(s): InvalidProvider. Valid providers: CapSolver, AntiCaptcha, YesCaptcha, CapMonster, SolveCaptcha, 2Captcha, EzCaptcha"
}
```
{% endtab %}

{% tab v1_post_captcha_providers_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v1_post_captcha_providers_example %}

{% tab v1_post_captcha_providers_example 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>"
     }'
```
{% endtab %}

{% tab v1_post_captcha_providers_example 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);
```
{% endtab %}

{% tab v1_post_captcha_providers_example 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())
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Google Flow API v1
nav_order: 200
---
## Configure Google Flow Account
{: .no_toc }

<small>November 17, 2025</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Configure your Google Flow account for API access using cookies from your authenticated Google account.

{: .post }
> **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](../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](../start-here/setup-google-flow) for detailed instructions on how to obtain these cookies.

### Responses

{% tabs v1_post_accounts_response %}

{% tab v1_post_accounts_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

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"
  }
}
```
{% endtab %}

{% tab v1_post_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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"
  }
}
```
{% endtab %}

{% tab v1_post_accounts_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error (missing/invalid parameters or cookies).

```json
{
  "error": "Failed to validate cookies: 401 Unauthorized"
}
```
{% endtab %}

{% tab v1_post_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_accounts_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% endtabs %}

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

{% tabs v1_post_accounts_example %}

{% tab v1_post_accounts_example 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..."
     }'
```
{% endtab %}

{% tab v1_post_accounts_example 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);
```
{% endtab %}

{% tab v1_post_accounts_example 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())
```
{% endtab %}

{% endtabs %}

### Try It

See [Setup Google Flow](../start-here/setup-google-flow#verify-cookies-value) 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/<code class="language-plaintext highlighter-rouge">email</code>
parent: Google Flow API v1
nav_order: 500
---
## Upload Assets
{: .no_toc }

<small>November 17, 2025 (February 27, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](https://useapi.net/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

{% tabs v1_post_assets_email_response %}

{% tab v1_post_assets_email_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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)

{% endtab %}

{% tab v1_post_assets_email_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_assets_email_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_assets_email_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_assets_email_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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"
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_assets_email_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

Google session refresh failed. The account needs to be reconfigured. Delete the account using [DELETE /accounts/<code class="language-plaintext highlighter-rouge">email</code>](https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by strictly following the procedure in [Setup Google Flow](../start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session: 500 Internal Server Error"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs v1_post_assets_email_example %}

{% tab v1_post_assets_email_example 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"
```
{% endtab %}

{% tab v1_post_assets_email_example 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);
```
{% endtab %}

{% tab v1_post_assets_email_example 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'))
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale
parent: Google Flow API v1
nav_order: 650
---
## Upscale Images
{: .no_toc }

<small>January 2, 2026 (February 14, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](https://useapi.net/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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

{% tabs v1_post_images_upscale_response %}

{% tab v1_post_images_upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_images_upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request (missing or invalid mediaGenerationId).

```json
{
  "error": "mediaGenerationId is required"
}
```
{% endtab %}

{% tab v1_post_images_upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_images_upscale_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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](../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
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_images_upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or image not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_images_upscale_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
      }
    ]
  }
}
```
{% endtab %}

{% endtabs %}

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

{% tabs v1_post_images_upscale_example %}

{% tab v1_post_images_upscale_example 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
```
{% endtab %}

{% tab v1_post_images_upscale_example 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!');
```
{% endtab %}

{% tab v1_post_images_upscale_example 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!')
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images
parent: Google Flow API v1
nav_order: 600
---
## Generate Images
{: .no_toc }

<small>November 17, 2025 (March 20, 2026)</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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. If you receive a `429 Too Many Requests` or `503 Service Unavailable` response, simply wait 5-10 seconds before retrying—both status codes indicate temporary capacity constraints and are safe to retry. If you consistently receive 429 errors, you may need to execute a cool-off period of at least a few hours before trying again. Image generation typically completes within 10-20 seconds.

**Important notes:**
- **Content moderation:** If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts as moderation decisions can vary between requests. Alternatively, switching between `imagen-4`, `nano-banana-2`, and `nano-banana-pro` models may help, as they have different content moderation behaviors.

{: .post }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](https://useapi.net/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 (default: `16:9`).
  Supported values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.
  Legacy aliases `landscape` (→ `16:9`) and `portrait` (→ `9:16`) are still accepted.
- `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`](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/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

{% tabs v1_post_images_response %}

{% tab v1_post_images_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
      }
    ]
  }
}
```

{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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"
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_images_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_images_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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](../support)

```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"
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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.

**Concurrency/rate limit error:**
```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"
      }
    ]
  }
}
```

**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"
        }
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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"
  }
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">503</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503" rel="noreferrer" target="_blank"><span class="http-status-bad">503 Service Unavailable</span></a>

Service temporarily unavailable or captcha provider error.

If the error is from Google (`"status": "UNAVAILABLE"`), wait 5-10 seconds and retry. If the error contains "Captcha service failed", do not retry — check your provider API key and balance via [POST /accounts/captcha-providers](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers).

```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
}
```
{% endtab %}

{% tab v1_post_images_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

Google session refresh failed. The account cookies needs to be updated following the instructions in [Setup Google Flow](../start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session."
}
```
{% endtab %}

{% endtabs %}

### Model

- `jobId` - Unique job identifier (for use with [GET /jobs/`jobId`](https://useapi.net/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
        }
    }>
  }
}
```

### Examples

{% tabs v1_post_images_example %}

{% tab v1_post_images_example 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...
```
{% endtab %}

{% tab v1_post_images_example 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;
}
```
{% endtab %}

{% tab v1_post_images_example 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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="16:9">16:9 (default)</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-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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/concatenate
parent: Google Flow API v1
nav_order: 740
---
## Concatenate Videos
{: .no_toc }

<small>January 29, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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

{% tabs v1_post_videos_concatenate_response %}

{% tab v1_post_videos_concatenate_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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..."
}
```
{% endtab %}

{% tab v1_post_videos_concatenate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request.

```json
{
  "error": "Error message",
  "code": 400
}
```
{% endtab %}

{% tab v1_post_videos_concatenate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_videos_concatenate_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_videos_concatenate_response <span class="http-status-bad">408</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408" rel="noreferrer" target="_blank"><span class="http-status-bad">408 Request Timeout</span></a>

Concatenation polling timeout (after 3 minutes).

```json
{
  "error": "Polling timeout"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs v1_post_videos_concatenate_example %}

{% tab v1_post_videos_concatenate_example 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
```
{% endtab %}

{% tab v1_post_videos_concatenate_example 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;
```
{% endtab %}

{% tab v1_post_videos_concatenate_example 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)')
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend
parent: Google Flow API v1
nav_order: 730
---
## Extend Videos
{: .no_toc }

<small>January 29, 2026 (February 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-concatenate) to remove overlap when combining clips.

{: .post }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos) or [POST /videos/extend](https://useapi.net/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-fast-relaxed` (Ultra only), `veo-3.1-quality`.
- `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`](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

{% tabs v1_post_videos_extend_response %}

{% tab v1_post_videos_extend_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_videos_extend_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Video extension is processing in the background.

Use [GET /jobs/`jobId`](https://useapi.net/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
    }
  }
}
```
{% endtab %}

{% tab v1_post_videos_extend_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request.

```json
{
  "error": "Error message",
  "code": 400
}
```
{% endtab %}

{% tab v1_post_videos_extend_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_videos_extend_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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](../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"
  }
}
```
{% endtab %}

{% tab v1_post_videos_extend_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_videos_extend_response <span class="http-status-bad">408</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408" rel="noreferrer" target="_blank"><span class="http-status-bad">408 Request Timeout</span></a>

Video extension polling timeout (after 10 minutes).

```json
{
  "error": "Polling timeout"
}
```
{% endtab %}

{% endtabs %}

### Model

{% tabs v1_post_videos_extend_model %}

{% tab v1_post_videos_extend_model <span class="http-status-good">200</span> 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
    }>
  }
}
```

{% endtab %}

{% tab v1_post_videos_extend_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobId`](https://useapi.net/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
    }
  }
}
```

{% endtab %}

{% tab v1_post_videos_extend_model <span class="http-status-bad">Error</span> %}

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
      }>
    }
  }
}
```

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_post_videos_extend_example %}

{% tab v1_post_videos_extend_example 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
```
{% endtab %}

{% tab v1_post_videos_extend_example 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!');
```
{% endtab %}

{% tab v1_post_videos_extend_example 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!')
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> or <a href="https://useapi.net/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-fast-relaxed">veo-3.1-fast-relaxed (Ultra only)</option>
          <option value="veo-3.1-quality">veo-3.1-quality</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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/gif
parent: Google Flow API v1
nav_order: 720
---
## Generate Video GIF
{: .no_toc }

<small>January 20, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos).

### Responses

{% tabs v1_post_videos_gif_response %}

{% tab v1_post_videos_gif_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

GIF generated successfully. Returns base64-encoded GIF data.

```json
{
  "encodedGif": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7...base64 encoded GIF data..."
}
```
{% endtab %}

{% tab v1_post_videos_gif_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request (missing or invalid mediaGenerationId).

```json
{
  "error": "mediaGenerationId is required"
}
```

**Invalid reference type:**
```json
{
  "error": "mediaGenerationId type must be 'video', got 'image'"
}
```
{% endtab %}

{% tab v1_post_videos_gif_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_videos_gif_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs v1_post_videos_gif_example %}

{% tab v1_post_videos_gif_example 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
```
{% endtab %}

{% tab v1_post_videos_gif_example 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;
```
{% endtab %}

{% tab v1_post_videos_gif_example 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!')
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale
parent: Google Flow API v1
nav_order: 710
---
## Upscale Videos
{: .no_toc }

<small>January 20, 2026 (February 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](https://useapi.net/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`](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details.

### Responses

{% tabs v1_post_videos_upscale_response %}

{% tab v1_post_videos_upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_videos_upscale_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Video upscaling is processing in the background.

Use [GET /jobs/`jobId`](https://useapi.net/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
    }
  }
}
```
{% endtab %}

{% tab v1_post_videos_upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request.

```json
{
  "error": "Error message"
}
```
{% endtab %}

{% tab v1_post_videos_upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_videos_upscale_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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](../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
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_videos_upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or video not found.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_videos_upscale_response <span class="http-status-bad">408</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408" rel="noreferrer" target="_blank"><span class="http-status-bad">408 Request Timeout</span></a>

Video upscaling polling timeout (after 10 minutes).

```json
{
  "error": "Polling timeout"
}
```
{% endtab %}

{% endtabs %}

### Model

{% tabs v1_post_videos_upscale_model %}

{% tab v1_post_videos_upscale_model <span class="http-status-good">200</span> 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
    }>
  }
}
```

{% endtab %}

{% tab v1_post_videos_upscale_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobId`](https://useapi.net/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
    }
  }
}
```

{% endtab %}

{% tab v1_post_videos_upscale_model <span class="http-status-bad">Error</span> %}

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
      }>
    }
  }
}
```

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_post_videos_upscale_example %}

{% tab v1_post_videos_upscale_example 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
```
{% endtab %}

{% tab v1_post_videos_upscale_example 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!');
```
{% endtab %}

{% tab v1_post_videos_upscale_example 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!')
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos
parent: Google Flow API v1
nav_order: 700
---
## Generate Videos
{: .no_toc }

<small>November 17, 2025 (April 3, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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 Fast Relaxed](https://deepmind.google/technologies/veo/), [Veo 3.1 Lite](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. If you receive a `429 Too Many Requests` or `503 Service Unavailable` response, simply wait 5-10 seconds before retrying—both status codes indicate temporary capacity constraints and are safe to retry. If you consistently receive 429 errors, you may need to execute a cool-off period of at least a few hours before trying again. 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 Fast Relaxed` 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 Fast Relaxed](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-fast-relaxed` | [Veo 3.1 Lite](https://deepmind.google/technologies/veo/)<br/>`veo-3.1-lite` |
|-----------|:---:|:---:|:---:|:---:|
| T2V (text-to-video) | ✓ | ✓ | ✓ | ✓ |
| I2V (start frame) | ✓ | ✓ | ✓ | ✓ |
| I2V-FL (start + end) | ✓ | ✓ | ✓ | ✓ |
| R2V (reference images 1-3) | ✗ | ✓ | ✓ | ✗ |
| Voice narration | ✗ | ✓ | ✓ | ✗ |
| Aspect ratios | all | all | all | all |
| `count` | ✓ (1-4) | ✓ (1-4) | ✓ (1-4) | ✓ (1-4) |
| `seed` | ✓ | ✓ | ✓ | ✓ |
| Subscription | all | all | Ultra only | all |
| Cost | 100 credits / $0.50 | 10 credits / $0.05 | free (lower priority) | 5 credits / $0.025 |


{: .post }
> **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](../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",
  "count": 2,
  "seed": 123456
}
```

- `email` is optional. The email address of the Google Flow account to use.

  When only one [account](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account.

  With multiple [accounts](https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](https://useapi.net/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-fast-relaxed` (Ultra only, no credits, lower priority), `veo-3.1-lite` (faster, lower cost).
- `aspectRatio` is optional, output video aspect ratio (default: `landscape`).  
  Supported values: `landscape` and `portrait`.
- `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`](https://useapi.net/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`](https://useapi.net/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`](https://useapi.net/docs/api-google-flow-v1/post-google-flow-assets-email) for R2V mode (1-3 reference images for style/composition). Only works with `veo-3.1-fast` and `veo-3.1-fast-relaxed` models.
- `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`](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/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` and `veo-3.1-fast-relaxed` models only
- Voice narration requires at least one `referenceImage` (R2V mode)

### Responses

{% tabs v1_post_videos_response %}

{% tab v1_post_videos_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
      }
    ]
  }
}
```

{% endtab %}

{% tab v1_post_videos_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Video generation is processing in the background.

Use [GET /jobs/`jobId`](https://useapi.net/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",
    "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
    }
  }
}
```

{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request (validation error, mode conflict, email mismatch, or content policy violation).

**Validation error:**
```json
{
  "error": "Reference-to-video mode requires veo-3.1-fast or veo-3.1-fast-relaxed model"
}
```

**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"
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_videos_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_videos_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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](../support)

```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"
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Google Flow account john@gmail.com not found"
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">408</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408" rel="noreferrer" target="_blank"><span class="http-status-bad">408 Request Timeout</span></a>

Video generation polling timeout (after 10 minutes).

```json
{
  "error": "Video generation polling timeout after 120 attempts (600s)"
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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"
      }
    ]
  }
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">503</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503" rel="noreferrer" target="_blank"><span class="http-status-bad">503 Service Unavailable</span></a>

Service temporarily unavailable or captcha provider error.

If the error is from Google (`"status": "UNAVAILABLE"`), wait 5-10 seconds and retry. If the error contains "Captcha service failed", do not retry — check your provider API key and balance via [POST /accounts/captcha-providers](https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers).

```json
{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable.",
    "status": "UNAVAILABLE"
  }
}
```

```json
{
  "error": "Captcha service failed: ERROR_ZERO_BALANCE",
  "code": 503
}
```
{% endtab %}

{% tab v1_post_videos_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

Google session refresh failed. The account needs to be reconfigured. Delete the account using [DELETE /accounts/<code class="language-plaintext highlighter-rouge">email</code>](https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by strictly following the procedure in [Setup Google Flow](../start-here/setup-google-flow).

```json
{
  "error": "Failed to refresh session: 500 Internal Server Error"
}
```
{% endtab %}

{% endtabs %}

### Model

{% tabs v1_post_videos_model %}

{% tab v1_post_videos_model <span class="http-status-good">200</span> 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
    }>
  }
}
```

{% endtab %}

{% tab v1_post_videos_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobId`](https://useapi.net/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
      }>
    }
  }
}
```

{% endtab %}

{% tab v1_post_videos_model <span class="http-status-bad">Error</span> %}

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
      }>
    }
  }
}
```

{% endtab %}

{% endtabs %}

### Examples

{% tabs v1_post_videos_example %}

{% tab v1_post_videos_example 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",
       "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
```
{% endtab %}

{% tab v1_post_videos_example 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',
    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));
}
```
{% endtab %}

{% tab v1_post_videos_example 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',
    '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)
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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-fast-relaxed">veo-3.1-fast-relaxed (Ultra only, no credits, lower priority)</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>
        </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-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="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: Setup Kling
parent: Start Here
nav_order: 210
---
# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/kling.svg"> Setup Kling 
{: .no_toc }

<small>April 18, 2025 (April 2, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 2 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [Kling API](../api-kling-v1). An active [Kling AI](https://kling.ai/app/) subscription and a [useapi.net subscription](../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](../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="https://useapi.net/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
---
layout: default
title: Kling API v1
nav_order: 4000
has_children: true
permalink: /docs/api-kling-v1
---

# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/kling.svg"> Kling API v1 

<small>April 18, 2025 (March 19, 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>(March 19, 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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Kling API v1
nav_order: 130
---
## Delete Kling API account configuration for `email`
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint removes a specific Kling account from your configuration.

{: .delete }
> **https://api.useapi.net/v1/kling/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts](https://useapi.net/docs/api-kling-v1/post-kling-accounts) request.

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

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

##### Responses 

{% tabs delete_account_Kling_v1_response %}

{% tab delete_account_Kling_v1_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>

Account successfully deleted.
{% endtab %}

{% tab delete_account_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_account_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account configuration not found.
{% endtab %}

{% endtabs %}

##### Examples

{% tabs delete_account_Kling_v1_example %}

{% tab delete_account_Kling_v1_example Curl %}
``` bash
curl -X DELETE https://api.useapi.net/v1/kling/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab delete_account_Kling_v1_example 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});
```
{% endtab %}

{% tab delete_account_Kling_v1_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> avatars/<code>avatarId</code>
parent: Kling API v1
nav_order: 465
---
## Delete avatar
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a specific avatar by its ID. Use [GET /avatars](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/post-kling-avatars). System template avatars cannot be deleted.

{: .delete }
> **https://api.useapi.net/v1/kling/avatars/`avatarId`?...**

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

- `API token` is **required**, see [Setup useapi.net](../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](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs avatars_avatarId_del_Kling_v1_response %}

{% tab avatars_avatarId_del_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "deleted": null
}
```

A `null` value indicates successful deletion.
{% endtab %}

{% tab avatars_avatarId_del_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab avatars_avatarId_del_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript
  deleted: null  // null indicates success
}
```

##### Examples

{% tabs avatars_avatarId_del_Kling_v1_example %}

{% tab avatars_avatarId_del_Kling_v1_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/avatars/123456789012?email=user@example.com" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab avatars_avatarId_del_Kling_v1_example 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});
```
{% endtab %}

{% tab avatars_avatarId_del_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> elements/<code>elementId</code>
parent: Kling API v1
nav_order: 428
---
## Delete element
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a specific element by its ID. Use [GET /elements](https://useapi.net/docs/api-kling-v1/get-kling-elements) to list your elements and get their IDs.

{: .delete }
> **https://api.useapi.net/v1/kling/elements/`elementId`?...**

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

- `API token` is **required**, see [Setup useapi.net](../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](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs elements_elementId_del_Kling_v1_response %}

{% tab elements_elementId_del_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "deleted": 1
}
```
{% endtab %}

{% tab elements_elementId_del_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab elements_elementId_del_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript
  deleted: number
}
```

##### Examples

{% tabs elements_elementId_del_Kling_v1_example %}

{% tab elements_elementId_del_Kling_v1_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab elements_elementId_del_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_elementId_del_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/<code class="language-plaintext highlighter-rouge">task_id</code>
parent: Kling API v1
nav_order: 520
---
## Cancel a running task
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **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](https://useapi.net/docs/api-kling-v1/get-kling-scheduler).

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

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

##### Responses 

{% tabs scheduler_task_id_delete_Kling_v1_response %}

{% tab scheduler_task_id_delete_Kling_v1_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>

Task was successfully canceled.
{% endtab %}

{% tab scheduler_task_id_delete_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Error ..."
}
```
{% endtab %}

{% tab scheduler_task_id_delete_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab scheduler_task_id_delete_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "Unable to locate running task_id 123456789"
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs scheduler_task_id_delete_Kling_v1_example %}

{% tab scheduler_task_id_delete_Kling_v1_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/scheduler/123456789" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab scheduler_task_id_delete_Kling_v1_example 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});
```
{% endtab %}

{% tab scheduler_task_id_delete_Kling_v1_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> tasks/<code class="language-plaintext highlighter-rouge">task_id</code>
parent: Kling API v1
nav_order: 307
---
## Delete Kling Task
{: .no_toc }

<small>October 7, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **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](../start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs tasks_task_id_delete_Kling_v1_response %}

{% tab tasks_task_id_delete_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "deleted": 1,
  "workIds": [987654321]
}
```

The response indicates how many works were deleted and their IDs.
{% endtab %}

{% tab tasks_task_id_delete_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid task_id parameter"
}
```
{% endtab %}

{% tab tasks_task_id_delete_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab tasks_task_id_delete_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Task was not found or has no associated works.

```json
{
  "error": "No works found for task 123456789"
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript, all fields are optional
  deleted: number     // Number of works deleted
  workIds: number[]   // Array of deleted work IDs
}
```

##### Examples

{% tabs tasks_task_id_delete_Kling_v1_example %}

{% tab tasks_task_id_delete_Kling_v1_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```
{% endtab %}

{% tab tasks_task_id_delete_Kling_v1_example 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});
```
{% endtab %}

{% tab tasks_task_id_delete_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Kling API v1
nav_order: 120
---
## Retrieve Kling API account configuration and balance for `email`
{: .no_toc }

<small>April 18, 2025 (June 23, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves the configuration and balance information for a specific Kling account.

{: .get }
> **https://api.useapi.net/v1/kling/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts](https://useapi.net/docs/api-kling-v1/post-kling-accounts) request.

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

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

##### Responses 

{% tabs account_email_Kling_v1_response %}

{% tab account_email_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
  }  
}
```
{% endtab %}

{% tab account_email_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_email_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-kling-v1/post-kling-accounts).

{% endtab %}

{% endtabs %}

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

{% tabs account_email_Kling_v1_example %}

{% tab account_email_Kling_v1_example Curl %}
``` bash
curl https://api.useapi.net/v1/kling/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_email_Kling_v1_example 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});
```
{% endtab %}

{% tab account_email_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Kling API v1
nav_order: 100
---
## Retrieve Kling API accounts configuration
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_Kling_v1_response %}

{% tab account_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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…"
    }
}
```
{% endtab %}

{% tab account_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-kling-v1/post-kling-accounts).

{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [email: string]: {
        email: string
        session: {
            userId: string
            ExpireTime: number
            ExpireTimeUTC: string
        }
        maxJobs: number
        password: string
    }
}
```

##### Examples

{% tabs account_Kling_v1_example %}

{% tab account_Kling_v1_example Curl %}
``` bash
curl https://api.useapi.net/v1/kling/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_Kling_v1_example 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});
```
{% endtab %}

{% tab account_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/download
parent: Kling API v1
nav_order: 205
---
## Download Kling assets without watermarks
{: .no_toc }

<small>April 18, 2025 (June 27, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint allows you to download assets from your *paid* Kling account without watermarks by providing the work IDs.

{: .get }
> **https://api.useapi.net/v1/kling/assets/download?…**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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](../api-kling-v1/get-kling-assets), [GET /tasks](../api-kling-v1/get-kling-tasks) or [GET /tasks/`task_id`](../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 

{% tabs assets_download_get_Kling_v1_response %}

{% tab assets_download_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "cdnUrl": "https://kling.klingai.com/.../download_result.zip",
  "status": "success"
}
```

{% endtab %}

{% tab assets_download_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid parameters"
}
```
{% endtab %}

{% tab assets_download_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript
  cdnUrl: string // URL to download the asset(s), .zip for multiple workIds
  status: string // "success" when successful
}
```

##### Examples

{% tabs assets_download_get_Kling_v1_example %}

{% tab assets_download_get_Kling_v1_example 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 …" 
```
{% endtab %}

{% tab assets_download_get_Kling_v1_example 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});
```
{% endtab %}

{% tab assets_download_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/uploaded
parent: Kling API v1
nav_order: 201
---
## Retrieve uploaded Kling assets
{: .no_toc }

<small>August 8, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves assets that you have uploaded to your Kling account, as opposed to generated assets.

{: .get }
> **https://api.useapi.net/v1/kling/assets/uploaded/?…**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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).

##### Responses 

{% tabs assets_uploaded_get_Kling_v1_response %}

{% tab assets_uploaded_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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": ""
    }
  ]
}
```
{% endtab %}

{% tab assets_uploaded_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid parameters"
}
```
{% endtab %}

{% tab assets_uploaded_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs assets_uploaded_get_Kling_v1_example %}

{% tab assets_uploaded_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab assets_uploaded_get_Kling_v1_example 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});
```
{% endtab %}

{% tab assets_uploaded_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-assets ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets
parent: Kling API v1
nav_order: 200
---
## Retrieve Kling assets
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves generated assets from your Kling account.

{: .get }
> **https://api.useapi.net/v1/kling/assets/?…**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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`.

##### Responses 

{% tabs assets_get_Kling_v1_response %}

{% tab assets_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
      }
    ]
  }
}
```
{% endtab %}

{% tab assets_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid parameters"
}
```
{% endtab %}

{% tab assets_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 

To download assets without watermarks, use the [GET /assets/download](../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

{% tabs assets_get_Kling_v1_example %}

{% tab assets_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab assets_get_Kling_v1_example 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});
```
{% endtab %}

{% tab assets_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> avatars
parent: Kling API v1
nav_order: 450
---
## List avatars
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-kling-v1/post-kling-avatars-video).

{: .get }
> **https://api.useapi.net/v1/kling/avatars/?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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](https://useapi.net/docs/api-kling-v1/post-kling-avatars)
  - `templates`: System-provided avatar templates

##### Responses

{% tabs avatars_get_Kling_v1_response %}

{% tab avatars_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

**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"
  }
]
```
{% endtab %}

{% tab avatars_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs avatars_get_Kling_v1_example %}

{% tab avatars_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/avatars/?email=user@example.com&type=personal" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab avatars_get_Kling_v1_example 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});
```
{% endtab %}

{% tab avatars_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/<code>elementId</code>
parent: Kling API v1
nav_order: 424
---
## Retrieve element by ID
{: .no_toc }

<small>January 12, 2026 (February 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves details for a specific element by its ID. Use [GET /elements](https://useapi.net/docs/api-kling-v1/get-kling-elements) to list all your elements and get their IDs.

{: .get }
> **https://api.useapi.net/v1/kling/elements/`elementId`?...**

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

- `API token` is **required**, see [Setup useapi.net](../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](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs elements_elementId_get_Kling_v1_response %}

{% tab elements_elementId_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab elements_elementId_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab elements_elementId_get_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs elements_elementId_get_Kling_v1_example %}

{% tab elements_elementId_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab elements_elementId_get_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_elementId_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/tags
parent: Kling API v1
nav_order: 420
---
## Retrieve available element tags
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves available element category tags. Tags are used to categorize elements when creating them via [POST /elements](https://useapi.net/docs/api-kling-v1/post-kling-elements) and for filtering when listing elements via [GET /elements](https://useapi.net/docs/api-kling-v1/get-kling-elements).

{: .get }
> **https://api.useapi.net/v1/kling/elements/tags/?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs elements_tags_get_Kling_v1_response %}

{% tab elements_tags_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"
    }
  ]
}
```
{% endtab %}

{% tab elements_tags_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript, all fields are optional
  tagList: {
    id: string
    tagKey: string
    name: string
    official: boolean
    type: string
  }[]
}
```

##### Examples

{% tabs elements_tags_get_Kling_v1_example %}

{% tab elements_tags_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/elements/tags/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab elements_tags_get_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_tags_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/voices
parent: Kling API v1
nav_order: 422
---
## Retrieve available element voices
{: .no_toc }

<small>February 9, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves available official voices for elements. Voices can be assigned to elements when creating them via [POST /elements](https://useapi.net/docs/api-kling-v1/post-kling-elements). Only elements with the `character` tag support voice assignment.

{: .get }
> **https://api.useapi.net/v1/kling/elements/voices/?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses

{% tabs elements_voices_get_Kling_v1_response %}

{% tab elements_voices_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "voices": [
    {
      "id": 1,
      "name": "Vivid Girl"
    },
    {
      "id": 2,
      "name": "Gentle Lady"
    },
    {
      "id": 3,
      "name": "Charming Uncle"
    }
  ]
}
```
{% endtab %}

{% tab elements_voices_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### 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](https://useapi.net/docs/api-kling-v1/post-kling-elements).

##### Examples

{% tabs elements_voices_get_Kling_v1_example %}

{% tab elements_voices_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/elements/voices/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab elements_voices_get_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_voices_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements
parent: Kling API v1
nav_order: 422
---
## List elements
{: .no_toc }

<small>January 12, 2026 (February 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](https://useapi.net/docs/api-kling-v1/post-kling-videos-omni) using the `@element_N` syntax.

{: .get }
> **https://api.useapi.net/v1/kling/elements/?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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](https://useapi.net/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

{% tabs elements_get_Kling_v1_response %}

{% tab elements_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab elements_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### 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](https://useapi.net/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](https://useapi.net/docs/api-kling-v1/post-kling-videos-omni):

```json
{
  "prompt": "Character @element_1 walking through a beautiful garden",
  "element_1": "u_123456789012345"
}
```

##### Examples

{% tabs elements_get_Kling_v1_example %}

{% tab elements_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/elements/?email=user@example.com&pageSize=10" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer ..."
```
{% endtab %}

{% tab elements_get_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available
parent: Kling API v1
nav_order: 510
---
## Retrieve available capacity
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves information about available capacity and currently running API tasks.

{: .get }
> **https://api.useapi.net/v1/kling/scheduler/available**

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

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

##### Responses 

{% tabs scheduler_available_get_Kling_v1_response %}

{% tab scheduler_available_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
    }
  ]
}
```
{% endtab %}

{% tab scheduler_available_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Error ..."
}
```
{% endtab %}

{% tab scheduler_available_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs scheduler_available_get_Kling_v1_example %}

{% tab scheduler_available_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab scheduler_available_get_Kling_v1_example 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});
```
{% endtab %}

{% tab scheduler_available_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: Kling API v1
nav_order: 500
---
## Retrieve running tasks
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves information about currently running API tasks.

{: .get }
> **https://api.useapi.net/v1/kling/scheduler**

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

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

##### Responses 

{% tabs scheduler_get_Kling_v1_response %}

{% tab scheduler_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"
  }
]
```
{% endtab %}

{% tab scheduler_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Error ..."
}
```
{% endtab %}

{% tab scheduler_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs scheduler_get_Kling_v1_example %}

{% tab scheduler_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/scheduler" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab scheduler_get_Kling_v1_example 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});
```
{% endtab %}

{% tab scheduler_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks/<code class="language-plaintext highlighter-rouge">task_id</code>
parent: Kling API v1
nav_order: 305
---
## Retrieve specific Kling task
{: .no_toc }

<small>April 18, 2025 (December 10, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves information about a specific task by its ID.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

{% tabs tasks_task_id_get_Kling_v1_response %}

{% tab tasks_task_id_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab tasks_task_id_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid task_id parameter"
}
```
{% endtab %}

{% tab tasks_task_id_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab tasks_task_id_get_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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`](../api-kling-v1/get-kling-accounts-email)

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% endtabs %}

##### 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](../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

{% tabs tasks_task_id_get_Kling_v1_example %}

{% tab tasks_task_id_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab tasks_task_id_get_Kling_v1_example 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});
```
{% endtab %}

{% tab tasks_task_id_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks ===
Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks
parent: Kling API v1
nav_order: 300
---
## Retrieve Kling tasks
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of tasks from your Kling account.

{: .get }
> **https://api.useapi.net/v1/kling/tasks/?…**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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 

{% tabs tasks_get_Kling_v1_response %}

{% tab tasks_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
      }
    ]
  }
}
```
{% endtab %}

{% tab tasks_get_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "createdAfter and createdBefore cannot be used together"
}
```
{% endtab %}

{% tab tasks_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### 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](../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

{% tabs tasks_get_Kling_v1_example %}

{% tab tasks_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/tasks/?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab tasks_get_Kling_v1_example 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});
```
{% endtab %}

{% tab tasks_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tts/voices
parent: Kling API v1
nav_order: 470
---
## Retrieve available TTS voices
{: .no_toc }

<small>April 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of available text-to-speech voices from Kling.

{: .get }
> **https://api.useapi.net/v1/kling/tts/voices?…**

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

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

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

{% tabs tts_voices_get_Kling_v1_response %}

{% tab tts_voices_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"]
}
```
{% endtab %}

{% tab tts_voices_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs tts_voices_get_Kling_v1_example %}

{% tab tts_voices_get_Kling_v1_example Curl %}
``` bash
curl "https://api.useapi.net/v1/kling/tts/voices?email=user@example.com" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab tts_voices_get_Kling_v1_example 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});
```
{% endtab %}

{% tab tts_voices_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/effects
parent: Kling API v1
nav_order: 320
---
## Get Available Video Effects
{: .no_toc }

<small>April 18, 2025 (July 25, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of available special effects that can be applied to videos when using the [POST /videos/image2video-effects](https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint.

{: .get }
> **https://api.useapi.net/v1/kling/videos/effects/?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

{% tabs videos_effects_get_Kling_v1_response %}

{% tab videos_effects_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
  }
]
```
{% endtab %}

{% tab videos_effects_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

The response contains an array of available effects that can be used with the [POST /videos/image2video-effects](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint

##### Examples

{% tabs videos_effects_get_Kling_v1_example %}

{% tab videos_effects_get_Kling_v1_example Curl %}
``` bash
curl -X GET "https://api.useapi.net/v1/kling/videos/effects?email=user@example.com" \
   -H "Authorization: Bearer …"
```
{% endtab %}

{% tab videos_effects_get_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_effects_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/motions
parent: Kling API v1
nav_order: 325
---
## Get Available Motions
{: .no_toc }

<small>October 7, 2025 (January 6, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of available motion assets. Official motion videos can be used as `motionUrl` in [POST /videos/motion-create](https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create). Uses Kling v2.6 modality asset API.

{: .get }
> **https://api.useapi.net/v1/kling/videos/motions?...**

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

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

##### Query Parameters

- `email` is optional when only one [account](../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](https://useapi.net/docs/api-kling-v1/post-kling-assets) - use `resourceUrl` from upload response

##### Responses

{% tabs videos_motions_get_Kling_v1_response %}

{% tab videos_motions_get_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
  }
]
```
{% endtab %}

{% tab videos_motions_get_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs videos_motions_get_Kling_v1_example %}

{% tab videos_motions_get_Kling_v1_example 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 ..."
```
{% endtab %}

{% tab videos_motions_get_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_motions_get_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Kling API v1
nav_order: 110
---
## Create/update Kling API account
{: .no_toc }

<small>April 18, 2025 (Jun 19, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint adds or updates a Kling account in your configuration. The API will automatically login to verify your credentials.

{: .post }
> **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](../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](../start-here/setup-kling) for details.  
  
- `maxJobs` is **required**, specify maximum number of concurrent jobs (`1`-`50`)

##### Responses 

{% tabs input_Kling_v1_response %}

{% tab input_Kling_v1_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>
```json
{
  "email": "user@example.com",
  "session": {
    "userId": "user12345",
    "ExpireTime": 123456789,
    "ExpireTimeUTC": "2025-01-01T12:13:14.000Z"
  },
  "maxJobs": 50,
  "password": "…secured…"
}
```
{% endtab %}

{% tab input_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Account does not exist or password is incorrect"
}
```
{% endtab %}

{% tab input_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab input_Kling_v1_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>
```json
{
  "error": "Subscription required",
  "code": 402
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string
  session: {
    userId: string
    ExpireTime: number
    ExpireTimeUTC: string
  }
  maxJobs: number
  password: string
  error: string
}
```

##### Examples

{% tabs input_Kling_v1_example %}

{% tab input_Kling_v1_example 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}'
```
{% endtab %}

{% tab input_Kling_v1_example 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});
```
{% endtab %}

{% tab input_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/post-kling-assets ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-assets
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets
parent: Kling API v1
nav_order: 210
---
## Upload asset to Kling
{: .no_toc }

<small>April 18, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint uploads an asset to your Kling account for later use in image and video generation.

{: .post }
> **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](../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            | 100MB    | 720p/1080p resolution, 10s max |
| video/quicktime     | mov            | 100MB    | 720p/1080p resolution, 10s max |
| audio/wav           | wav            | 20MB     | 30 seconds max |
| audio/wave          | wav            | 20MB     | 30 seconds max |
| audio/mpeg          | mp3            | 20MB     | 30 seconds max |
| audio/mp4           | m4a            | 20MB     | 30 seconds max |
| audio/flac          | flac           | 20MB     | 30 seconds max |
| audio/aac           | aac            | 20MB     | 30 seconds max |
| audio/ogg           | ogg            | 20MB     | 30 seconds max |

##### Query Parameters

- `email` is optional when only one [account](../api-kling-v1/get-kling-accounts) configured.  
  However, if you have multiple accounts configured, this parameter becomes **required**.

##### Responses 

{% tabs assets_post_Kling_v1_response %}

{% tab assets_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "status": 3,
  "url": "https://s21-kling.klingai.com/....jpg",
  "message": "",
  "fileName": "abc123def456789.jpg"
}
```
{% endtab %}

{% tab assets_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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"
}
```
{% endtab %}

{% tab assets_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab assets_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}


You can retrieve uploaded asset details via [GET assets/uploaded/?fileName=`fileName`](https://useapi.net/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

{% tabs assets_post_Kling_v1_example %}

{% tab assets_post_Kling_v1_example 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
```
{% endtab %}

{% tab assets_post_Kling_v1_example 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});
```
{% endtab %}

{% tab assets_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> avatars/video
parent: Kling API v1
nav_order: 460
---
## Generate avatar video
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/post-kling-assets))
- Text that will be converted to speech using TTS

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses

{% tabs avatars_video_post_Kling_v1_response %}

{% tab avatars_video_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab avatars_video_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab avatars_video_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab avatars_video_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs avatars_video_post_Kling_v1_example %}

{% tab avatars_video_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab avatars_video_post_Kling_v1_example 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});
```
{% endtab %}

{% tab avatars_video_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> avatars
parent: Kling API v1
nav_order: 455
---
## Create avatar
{: .no_toc }

<small>January 12, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint creates a new avatar from an image. Avatars are digital characters that can be animated with lip-sync using [POST /avatars/video](https://useapi.net/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.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/get-kling-tts-voices) for each speaker's supported emotions.

##### Responses

{% tabs avatars_post_Kling_v1_response %}

{% tab avatars_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "id": "300137233318846",
  "status": "SUCCESS"
}
```

Use [GET /avatars](https://useapi.net/docs/api-kling-v1/get-kling-avatars) to retrieve the full avatar details after creation.
{% endtab %}

{% tab avatars_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab avatars_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript
  id: string
  status: 'SUCCESS' | 'FAILED'
}
```

##### Examples

{% tabs avatars_post_Kling_v1_example %}

{% tab avatars_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab avatars_post_Kling_v1_example 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});
```
{% endtab %}

{% tab avatars_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-kling-v1/post-kling-elements ===
Document URL: https://useapi.net/docs/api-kling-v1/post-kling-elements
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> elements
parent: Kling API v1
nav_order: 426
---
## Create element
{: .no_toc }

<small>January 12, 2026 (March 6, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/docs/api-kling-v1/del-kling-elements-elementId).

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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

{% tabs elements_post_Kling_v1_response %}

{% tab elements_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

**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
}
```
{% endtab %}

{% tab elements_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab elements_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### 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](https://useapi.net/docs/api-kling-v1/post-kling-images-omni), [POST /videos/omni](https://useapi.net/docs/api-kling-v1/post-kling-videos-omni), and [POST /videos/motion-create](https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create):

```json
{
  "prompt": "Character @element_1 walking through a beautiful garden",
  "element_1": "u_123456789012345"
}
```

##### Examples

{% tabs elements_post_Kling_v1_example %}

{% tab elements_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab elements_post_Kling_v1_example 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});
```
{% endtab %}

{% tab elements_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/kolors-elements
parent: Kling API v1
nav_order: 313
---
## Generate Images with KOLORS Elements
{: .no_toc }

<small>July 18, 2025 (October 31, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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 

{% tabs images_kolors_elements_post_Kling_v1_response %}

{% tab images_kolors_elements_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "At least two images must be provided"
}
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs images_kolors_elements_post_Kling_v1_example %}

{% tab images_kolors_elements_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_kolors_elements_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/kolors
parent: Kling API v1
nav_order: 312
---
## Generate Images with KOLORS
{: .no_toc }

<small>April 24, 2025 (February 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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) | ❌ |

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

{% tabs images_kolors_post_Kling_v1_response %}

{% tab images_kolors_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "reference \"face\" does not support subjectStrength"
}
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs images_kolors_post_Kling_v1_example %}

{% tab images_kolors_post_Kling_v1_example 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
   }'
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_kolors_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/omni
parent: Kling API v1
nav_order: 310
---
## Generate Images with Omni
{: .no_toc }

<small>December 10, 2025 (March 19, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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) | ✅ | ❌ |

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses

{% tabs images_omni_post_Kling_v1_response %}

{% tab images_omni_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab images_omni_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab images_omni_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_omni_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab images_omni_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs images_omni_post_Kling_v1_example %}

{% tab images_omni_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab images_omni_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_omni_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/recognize-faces
parent: Kling API v1
nav_order: 314
---
## Detect Faces in Images
{: .no_toc }

<small>April 24, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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.

{: .post }
> **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](../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](../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](https://useapi.net/docs/api-kling-v1/post-kling-assets) and use the returned URL here.

##### Responses 

{% tabs images_recognize_faces_post_Kling_v1_response %}

{% tab images_recognize_faces_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
  }
}
```
{% endtab %}

{% tab images_recognize_faces_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter imageReference is required"
}
```
{% endtab %}

{% tab images_recognize_faces_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_recognize_faces_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs images_recognize_faces_post_Kling_v1_example %}

{% tab images_recognize_faces_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab images_recognize_faces_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_recognize_faces_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale
parent: Kling API v1
nav_order: 316
---
## Upscale Images
{: .no_toc }

<small>April 24, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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`](https://useapi.net/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`](https://useapi.net/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`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

{% tabs images_upscale_post_Kling_v1_response %}

{% tab images_upscale_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab images_upscale_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Task 123456789 is not completed"
}
```
{% endtab %}

{% tab images_upscale_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_upscale_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs images_upscale_post_Kling_v1_example %}

{% tab images_upscale_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab images_upscale_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_upscale_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/virtual-try-on
parent: Kling API v1
nav_order: 310
---
## Virtual Try-On
{: .no_toc }

<small>April 18, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint allows you to create virtual try-on images with Kling AI by providing a human image and clothing items.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/post-kling-assets).

- `upperInput` URL to an upper garment image.  
  Incompatible with dressInput. Images can be uploaded using [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets).
   
- `lowerInput` URL to a lower garment image.  
  Incompatible with dressInput. Images can be uploaded using [POST /assets](https://useapi.net/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`](https://useapi.net/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 

{% tabs images_virtual_try_on_post_Kling_v1_response %}

{% tab images_virtual_try_on_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "At least one of dressInput, upperInput or lowerInput must be provided"
}
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs images_virtual_try_on_post_Kling_v1_example %}

{% tab images_virtual_try_on_post_Kling_v1_example 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
   }'
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_example 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});
```
{% endtab %}

{% tab images_virtual_try_on_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> tts/create
parent: Kling API v1
nav_order: 475
---
## Generate speech from text
{: .no_toc }

<small>April 18, 2025 (December 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](https://useapi.net/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 

{% tabs tts_create_post_Kling_v1_response %}

{% tab tts_create_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "resource": "https://s21-kling.klingai.com/....mp3",
  "status": 99,
  "duration": 195621,
  "status_name": "succeed",
  "status_final": true
}
```
{% endtab %}

{% tab tts_create_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab tts_create_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab tts_create_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs tts_create_post_Kling_v1_example %}

{% tab tts_create_post_Kling_v1_example 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!"}'
```
{% endtab %}

{% tab tts_create_post_Kling_v1_example 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});
```
{% endtab %}

{% tab tts_create_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/add-sound
parent: Kling API v1
nav_order: 385
---
## Add sound to Kling video
{: .no_toc }

<small>August 8, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](https://useapi.net/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.  
  See [useapi.net Webhooks](../../webhooks).

- `replyRef` is optional, include a custom reference to identify the job.  
  Passed as-is to the `replyUrl` webhook.

##### Responses 

{% tabs videos_add_sound_post_Kling_v1_response %}

{% tab videos_add_sound_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Invalid video URL format"
}
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_add_sound_post_Kling_v1_example %}

{% tab videos_add_sound_post_Kling_v1_example 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"
  }'
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_add_sound_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend
parent: Kling API v1
nav_order: 370
---
## Extend an Existing Video
{: .no_toc }

<small>April 18, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint extends a previously generated video, continuing the animation from where it left off.

{: .post }
> **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](../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](../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](https://useapi.net/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`](https://useapi.net/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 

{% tabs videos_extend_post_Kling_v1_response %}

{% tab videos_extend_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_extend_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Task is not completed"
}
```
{% endtab %}

{% tab videos_extend_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_extend_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_extend_post_Kling_v1_example %}

{% tab videos_extend_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_extend_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_extend_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/image2video-effects
parent: Kling API v1
nav_order: 360
---
## Create Video From Image with Effects
{: .no_toc }

<small>April 18, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint generates a video from an image using special effects.

{: .post }
> **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](../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](../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](https://useapi.net/docs/api-kling-v1/get-kling-videos-effects).
  
- `image` is **required**, URL to the image to animate.   
  Image can be uploaded using [POST /assets](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/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 

{% tabs videos_image2video_effects_post_Kling_v1_response %}

{% tab videos_image2video_effects_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Effect rocket not found. Supported effects: cartoon,cyberpunk,spinoff"
}
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_image2video_effects_post_Kling_v1_example %}

{% tab videos_image2video_effects_post_Kling_v1_example 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"
  }'
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_image2video_effects_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/image2video-elements
parent: Kling API v1
nav_order: 350
---
## Create Video From Multiple Images
{: .no_toc }

<small>April 18, 2025 (February 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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) | ✅ |

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/get-kling-elements). Model `3.0` only.
  Create elements using [POST /elements](https://useapi.net/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) or `pro` (higher quality, slower generation).

- `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`](https://useapi.net/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 

{% tabs videos_image2video_elements_post_Kling_v1_response %}

{% tab videos_image2video_elements_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "At least one image (image_0, image_1, image_2 or image_3) is required"
}
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_image2video_elements_post_Kling_v1_example %}

{% tab videos_image2video_elements_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_image2video_elements_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/image2video-frames
parent: Kling API v1
nav_order: 340
---
## Create Video From Image Frames
{: .no_toc }

<small>April 18, 2025 (February 16, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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 |

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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) or `pro` (higher quality, slower generation).
  Model `2.6` supports both modes, but `pro` is required when `enable_audio` is `true`.

- `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`](https://useapi.net/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 

{% tabs videos_image2video_frames_post_Kling_v1_response %}

{% tab videos_image2video_frames_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "image or image_tail is required"
}
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_image2video_frames_post_Kling_v1_example %}

{% tab videos_image2video_frames_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_image2video_frames_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/lipsync
parent: Kling API v1
nav_order: 380
---
## Apply Lip Sync to Video
{: .no_toc }

<small>April 18, 2025 (October 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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 

{% tabs videos_lipsync_post_Kling_v1_response %}

{% tab videos_lipsync_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter video is required"
}
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_lipsync_post_Kling_v1_example %}

{% tab videos_lipsync_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_lipsync_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/motion-create
parent: Kling API v1
nav_order: 390
---
## Create Video from Motion and Image
{: .no_toc }

<small>October 7, 2025 (March 6, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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

{% tabs videos_motion_create_post_Kling_v1_response %}

{% tab videos_motion_create_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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": ""
}
```
{% endtab %}

{% tab videos_motion_create_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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."
  }
}
```
{% endtab %}

{% tab videos_motion_create_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_motion_create_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_motion_create_post_Kling_v1_example %}

{% tab videos_motion_create_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_motion_create_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_motion_create_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/motion-upload
nav_order: 385
nav_exclude: true
---
## Upload Custom Motion
{: .no_toc }

<small>October 7, 2025 (January 6, 2026)</small>

<span class="required-input-field"><b>This endpoint is no longer used.</b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create) endpoint to apply the motion to different images.

{: .post }
> **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](../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](../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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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](https://useapi.net/docs/api-kling-v1/get-kling-videos-motions) with `mine=true`)
- To delete a user-uploaded motion, use [DELETE /tasks/`task_id`](https://useapi.net/docs/api-kling-v1/del-kling-tasks-task_id) with the motion's `taskId` from the motions list

##### Responses

{% tabs videos_motion_upload_post_Kling_v1_response %}

{% tab videos_motion_upload_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter resourceUrl is required"
}
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](https://useapi.net/docs/api-kling-v1/post-kling-assets) to upload assets.

```json
{
    "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)",
    "message": "Not Found"
}
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id). Once processing completes, the extracted motion will be available in [GET /videos/motions](https://useapi.net/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

{% tabs videos_motion_upload_post_Kling_v1_example %}

{% tab videos_motion_upload_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_motion_upload_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/omni
parent: Kling API v1
nav_order: 330
---
## Generate Videos with Omni
{: .no_toc }

<small>December 11, 2025 (February 16, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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) |

{: .post }
> **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](../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](../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`.

###### 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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/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`](https://useapi.net/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

{% tabs videos_omni_post_Kling_v1_response %}

{% tab videos_omni_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "<error message>"
}
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_omni_post_Kling_v1_example %}

{% tab videos_omni_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_omni_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/text2video
parent: Kling API v1
nav_order: 330
---
## Create Video From Text
{: .no_toc }

<small>April 18, 2025 (February 16, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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 | ❌ | ❌ | ❌ | ❌ | ✅ |

{: .post }
> **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](../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](../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) or `pro` (higher quality, slower generation).
  Model `2.6` supports both modes, but `pro` is required when `enable_audio` is `true`.

- `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`](https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model.

- `replyRef` is optional, a reference identifier for the callback.

##### Responses 

{% tabs videos_text2video_post_Kling_v1_response %}

{% tab videos_text2video_post_Kling_v1_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab videos_text2video_post_Kling_v1_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter prompt is required"
}
```
{% endtab %}

{% tab videos_text2video_post_Kling_v1_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab videos_text2video_post_Kling_v1_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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)"
}
```
{% endtab %}

{% endtabs %}

When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](https://useapi.net/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

{% tabs videos_text2video_post_Kling_v1_example %}

{% tab videos_text2video_post_Kling_v1_example 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"
   }'
```
{% endtab %}

{% tab videos_text2video_post_Kling_v1_example 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});
```
{% endtab %}

{% tab videos_text2video_post_Kling_v1_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/start-here/setup-luma ===
Document URL: https://useapi.net/docs/start-here/setup-luma
---
layout: default
title: Setup Luma
# parent: Start Here
nav_order: 207
nav_exclude: true
---
# <img src="https://useapi.net/assets/images/luma.svg" style="height:1.5em;vertical-align: middle;"> Luma Dream Machine
{: .no_toc }

<small>April 6, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 15 minutes to complete setup steps.</small>

---

{: .note }
> This is the setup guide for [Luma API](../api-luma-v1). This is an [experimental](../../docs/legal) API. An active [Luma Dream Machine](https://lumalabs.ai/dream-machine) subscription and a [useapi.net subscription](../subscription) are required for the API to work.

[Luma Dream Machine](https://lumalabs.ai/dream-machine) creates AI-generated videos and images using Luma AI's proprietary models. Video models: [Ray v3](https://lumalabs.ai/dream-machine), [Ray v3 Flash](https://lumalabs.ai/dream-machine), and [Ray v3 Reasoning](https://lumalabs.ai/dream-machine). Image models: [Photon v2](https://lumalabs.ai/dream-machine) and [Image v2](https://lumalabs.ai/dream-machine).

### Create a Luma account

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

{: .important }
> You **must** create your account using the **email + password** option (called **Enterprise Sign In** on Luma's login page). Google Sign In and Apple Sign In will **not** work — the API needs the session cookie which is only available through the email/password login flow.

1. Navigate to [https://dream-machine.lumalabs.ai](https://dream-machine.lumalabs.ai)
2. Click **Enterprise Sign In** (bottom option on the login page)
3. Enter your dedicated email address → click Continue
4. Set a password → click Sign In
5. Verify your email if prompted

### Subscribe to a plan

You can test the API with a **free account** (limited to draft resolution, 1 concurrent slot), but most models and higher resolutions require a paid subscription. The **Unlimited** plan ($99.99/mo) is recommended — it provides unlimited generations at all resolutions with 4 concurrent slots.

1. Navigate to [https://dream-machine.lumalabs.ai](https://dream-machine.lumalabs.ai) and log in
2. Go to your account settings or subscription page
3. Select a plan and complete the subscription process

### Extract session cookie

You only need to extract **one value** — the `session` cookie (~25 characters). The API derives everything else automatically.

{: .note }
> You need to open Developer Tools **before** logging in, because the cookie is set during the login response.

#### 1. Open Developer Tools before logging in

1. Navigate to [https://dream-machine.lumalabs.ai](https://dream-machine.lumalabs.ai) <span style="color: red;">`1`</span> — **log out** first if you're already logged in
2. Open Developer Tools (**F12**) → go to the **Network** tab <span style="color: red;">`2`</span>
3. Check **Preserve log** <span style="color: red;">`3`</span> and **Disable cache** <span style="color: red;">`4`</span> at the top of the Network tab
5. Click **Enterprise Sign In** and log in with your email and password <span style="color: red;">`5`</span>

![Developer Tools with Preserve log and Disable cache enabled](/assets/images/luma-setup-1.jpg)

#### 2. Capture the `session` cookie from login response

1. In the Network tab, filter by `/password` <span style="color: red;">`1`</span> to find the request `POST https://auth.lumalabs.ai/password` <span style="color: red;">`2`</span>
2. Click on it → **Headers** tab <span style="color: red;">`3`</span> → scroll to **Response Headers** → look for `Set-Cookie` entries
3. Copy the value of the **`session`** cookie <span style="color: red;">`4`</span> (a short random string, ~25 characters):

![POST /password response showing session Set-Cookie header](/assets/images/luma-setup-2.jpg)

| Cookie | Looks like | Description |
|--------|-----------|-------------|
| `session` | `mK8jP2xZc9AfQw3LnT7vYbE1R` (~25 chars) | session cookie — **this is the only value you need** |

### Verify and add account

Use the form below to add your Luma account. You can also use [POST /accounts](../api-luma-v1/post-luma-accounts) directly.

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

      const body = { session: document.getElementById('post-accounts-Luma-session')?.value?.trim() };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

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

<form id="post-accounts-Luma" onsubmit="apiTestAccountLuma(document.getElementById('post-accounts-Luma-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Luma-api_token"><span>API Token<small> (see <a href="https://useapi.net/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Luma-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Luma-session"><span>session <small>(session cookie from step 5-7 above)</small></span>
        <input id="post-accounts-Luma-session" type="text" class="input-element" required aria-required="true">
      </label>
      <label for="post-accounts-Luma-action"><span>action</span>
        <select id="post-accounts-Luma-action" class="input-element">
          <option value="verify">Verify — test session only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-Luma-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

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

=== URL: https://useapi.net/docs/api-luma-v1/delete-luma-accounts-email ===
Document URL: https://useapi.net/docs/api-luma-v1/delete-luma-accounts-email
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Luma API v1
nav_order: 400
---
## Delete Account Configuration
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Delete a configured Luma 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](https://useapi.net/docs/api-luma-v1/post-luma-accounts) if you want to use it again.

{: .delete }
> **https://api.useapi.net/v1/luma/accounts/`email`**

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

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

### Path Parameters

- `email` is **required**. Luma account email (e.g. `user@example.com`).

### Responses

{% tabs v1_delete_luma_accounts_response %}

{% tab v1_delete_luma_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Account deleted successfully.

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

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

{% endtab %}

{% tab v1_delete_luma_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_luma_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured. Returns empty body with status 404.

{% endtab %}

{% endtabs %}

### Model
```typescript
{
  account: string                // Deleted account email
  deleted: boolean               // Always true on success
  remaining: number              // Number of other accounts still configured
  error?: string                 // Error message
}
```

### Examples

{% tabs v1_delete_luma_accounts_example %}

{% tab v1_delete_luma_accounts_example Curl %}
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/luma/accounts/user@example.com"
```
{% endtab %}

{% tab v1_delete_luma_accounts_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN';
const email = 'user@example.com';

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

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

{% tab v1_delete_luma_accounts_example Python %}
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
email = 'user@example.com'

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

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

print('Delete result:', response.json())
```
{% endtab %}

{% endtabs %}


### Try It

<script>
  async function apiExecuteDeleteLumaAccountsEmail() {
    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/luma/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="https://useapi.net/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="user@example.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteLumaAccountsEmail()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/delete-luma-jobs-jobid ===
Document URL: https://useapi.net/docs/api-luma-v1/delete-luma-jobs-jobid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Luma API v1
nav_order: 900
---
## Delete Job
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Remove a completed or failed job from the executing jobs tracker. Use this to clean up jobs that are no longer needed in the active queue.

{: .delete }
> **https://api.useapi.net/v1/luma/jobs/`jobid`**

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

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

### Path Parameters

- `jobid` is **required**, the unique job identifier returned from [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos) or [POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images).

### Responses

{% tabs v1_delete_luma_jobs_jobid_response %}

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Job successfully removed from the executing tracker.

```json
{
  "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "deleted": true
}
```

- `jobid` - The job identifier that was deleted.
- `deleted` - Confirmation of deletion (`true`).

{% endtab %}

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid job ID format.

```json
{
  "error": "Invalid jobid"
}
```
{% endtab %}

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

Job does not belong to this user.

```json
{
  "error": "Job does not belong to this user"
}
```
{% endtab %}

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found or has expired.

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

{% tab v1_delete_luma_jobs_jobid_response <span class="http-status-bad">409</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409" rel="noreferrer" target="_blank"><span class="http-status-bad">409 Conflict</span></a>

Cannot delete a job that is not in a terminal state.

```json
{
  "error": "Cannot delete job in state 'processing'. Wait for completion."
}
```
{% endtab %}

{% endtabs %}

### Model

```typescript
{
  jobid: string                    // Job identifier that was deleted
  deleted: true                    // Confirmation of deletion
  error?: string                   // Error message
}
```

### Examples

{% tabs v1_delete_luma_jobs_jobid_example %}

{% tab v1_delete_luma_jobs_jobid_example Curl %}
```bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/luma/jobs/j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma"
```
{% endtab %}

{% tab v1_delete_luma_jobs_jobid_example JavaScript %}
```javascript
const token = 'YOUR_API_TOKEN'
const jobId = 'j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma'

const response = await fetch(`https://api.useapi.net/v1/luma/jobs/${jobId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

const result = await response.json()
console.log('Deleted:', result.deleted)
```
{% endtab %}

{% tab v1_delete_luma_jobs_jobid_example Python %}
```python
import requests

token = 'YOUR_API_TOKEN'
job_id = 'j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma'

response = requests.delete(
    f'https://api.useapi.net/v1/luma/jobs/{job_id}',
    headers={'Authorization': f'Bearer {token}'}
)

result = response.json()
print(f"Deleted: {result['deleted']}")
```
{% endtab %}

{% endtabs %}

### Try It

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

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

    await apiExecute(
      `https://api.useapi.net/v1/luma/jobs/${jobidElement.value}`,
      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="https://useapi.net/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="apiExecuteDeleteLumaJobsJobId()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/get-luma-accounts-email ===
Document URL: https://useapi.net/docs/api-luma-v1/get-luma-accounts-email
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Luma API v1
nav_order: 350
---
## Get Account Configuration
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Get configuration details for a specific Luma account, including session validity, executing jobs, and credit balance.

{: .get }
> **https://api.useapi.net/v1/luma/accounts/`email`**

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

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

### Path Parameters

- `email` is **required**. Luma account email (e.g. `user@example.com`).

### Responses

{% tabs v1_get_luma_accounts_email_response %}

{% tab v1_get_luma_accounts_email_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Account details retrieved with live data from upstream.

```json
{
  "account": "user@example.com",
  "email": "user@example.com",
  "user_id": "9ecac364-4b63-5b61-9241-297345710d63",
  "concurrency": 4,
  "luma_session_expires": "2026-05-27 02:20:34 UTC",
  "updated": "2026-03-28",
  "luma_session": "eyJ…redacted…abc",
  "session": "mK8…redacted…1R",
  "sessionValid": true,
  "executing": 2,
  "credits": {
    "usage": 20,
    "limit": 500
  }
}
```

**Note:** The `luma_session` and `session` fields are redacted. The `sessionValid`, `executing`, and `credits` fields are fetched live from upstream.

{% endtab %}

{% tab v1_get_luma_accounts_email_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_luma_accounts_email_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured. Returns empty body with status 404.

{% endtab %}

{% endtabs %}

### Model
```typescript
{
  account: string                // "user@example.com"
  email: string
  user_id: string
  concurrency: number
  luma_session_expires: string   // ISO 8601 timestamp

  updated: string                // ISO 8601 timestamp
  refresh_last?: string          // ISO 8601 timestamp of last session refresh
  refresh_count: number          // Total number of session refreshes
  luma_session: string           // Redacted session token
  session: string                // Redacted session cookie
  sessionValid: boolean          // Whether session is still valid
  executing: number              // Number of currently executing jobs
  credits: {
    usage: number
    limit: number
  } | null
  error?: string                 // Error message
}
```

### Examples

{% tabs v1_get_luma_accounts_email_example %}

{% tab v1_get_luma_accounts_email_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/luma/accounts/user@example.com"
```
{% endtab %}

{% tab v1_get_luma_accounts_email_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN';
const email = 'user@example.com';

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

const accountConfig = await response.json();
console.log('Account:', accountConfig);
console.log('Session valid:', accountConfig.sessionValid);
console.log('Credits:', accountConfig.credits);
```
{% endtab %}

{% tab v1_get_luma_accounts_email_example Python %}
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
email = 'user@example.com'

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

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

account_config = response.json()
print('Account:', account_config)
print('Session valid:', account_config.get('sessionValid'))
print('Credits:', account_config.get('credits'))
```
{% endtab %}

{% endtabs %}


### Try It

<script>
  async function apiExecuteGetLumaAccountsEmail() {
    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/luma/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="https://useapi.net/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="user@example.com">
      </label>
    </div>
    <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetLumaAccountsEmail()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/get-luma-accounts ===
Document URL: https://useapi.net/docs/api-luma-v1/get-luma-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Luma API v1
nav_order: 300
---
## List All Configured Accounts
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all configured Luma accounts.

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

{: .get }
> **https://api.useapi.net/v1/luma/accounts**

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

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

### Responses

{% tabs v1_get_luma_accounts_response %}

{% tab v1_get_luma_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Returns a map of all configured accounts, keyed by email.

```json
{
  "user@example.com": {
    "account": "user@example.com",
    "email": "user@example.com",
    "user_id": "9ecac364-4b63-5b61-9241-297345710d63",
    "concurrency": 4,
    "luma_session_expires": "2026-05-27 02:20:34 UTC",
    "updated": "2026-03-28",
    "executing": 0
  }
}
```

{% endtab %}

{% tab v1_get_luma_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_luma_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

No accounts are configured. Returns an empty response with status 404.

{% endtab %}

{% endtabs %}

### Model
```typescript
// Map of email to account summary
{
  [email: string]: {
    account: string
    email: string
    user_id: string
    concurrency: number
    luma_session_expires: string // ISO 8601 timestamp
    updated: string
    refresh_last?: string        // ISO 8601 timestamp of last session refresh
    refresh_count: number        // Total number of session refreshes
    executing: number            // Currently executing jobs for this account
    error?: string
  }
}
```

### Examples

{% tabs v1_get_luma_accounts_example %}

{% tab v1_get_luma_accounts_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/luma/accounts"
```
{% endtab %}

{% tab v1_get_luma_accounts_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN';

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

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

{% tab v1_get_luma_accounts_example Python %}
``` python
import requests

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

response = requests.get('https://api.useapi.net/v1/luma/accounts', headers=headers)
print('All accounts:', response.json())
```
{% endtab %}

{% endtabs %}


### Try It

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

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

    await apiExecute('https://api.useapi.net/v1/luma/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="https://useapi.net/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="apiExecuteGetLumaAccounts()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid ===
Document URL: https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Luma API v1
nav_order: 800
---
## Retrieve Job Status
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve the status and result of a video or image generation job by its job ID. Fetches fresh status directly from the Luma API.

Use this endpoint to poll for completion after submitting a video via [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos) or images via [POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images).

{: .get }
> **https://api.useapi.net/v1/luma/jobs/`jobid`**

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

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

### Path Parameters

- `jobid` is **required**, the unique job identifier returned from [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos) or [POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images).

### Responses

{% tabs v1_get_luma_jobs_jobid_response %}

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Returns the job record with current status and details.

**Pending/Processing (video):**

```json
{
  "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "type": "video",
  "status": "pending",
  "created": "2026-03-26T14:05:30.123Z",
  "updated": null,
  "response": null,
  "credits": null
}
```

**Completed (video):**

```json
{
  "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "type": "video",
  "status": "completed",
  "created": "2026-03-26T14:05:30.123Z",
  "updated": "2026-03-26T14:08:45.678Z",
  "response": {
    "video": {
      "media_type": "video",
      "url": "https://storage.cdn-luma.com/...",
      "width": 1280,
      "height": 720,
      "duration": 5.04
    },
    "video_hdr_exr": null,
    "thumbnail": {
      "media_type": "image",
      "url": "https://storage.cdn-luma.com/.../thumbnail.jpg",
      "width": 1280,
      "height": 720
    },
    "last_frame": {
      "media_type": "image",
      "url": "https://storage.cdn-luma.com/.../last_frame.jpg",
      "width": 1280,
      "height": 720
    }
  },
  "credits": {
    "dm_usage": 20,
    "dm_relaxed_usage": null
  }
}
```

**Note on HDR video:** When `dynamic_range` is `hdr` or `hdr_exr`, the `response.video` URL points to a **HEVC (H.265) Main 10, BT.2020, HDR10 (PQ) MP4** file. This format is **not playable in web browsers** — use VLC, mpv, or a native HDR-capable player. When `hdr_exr`, `response.video_hdr_exr` contains a ZIP with EXR frames.

**Completed (image):**

```json
{
  "jobid": "j0326140530123456789i-u12345-email:user@example.com-gen:c3d4e5f6-a7b8-9012-cdef-345678901234-bot:luma",
  "type": "image",
  "status": "completed",
  "created": "2026-03-26T14:05:30.123Z",
  "updated": "2026-03-26T14:06:15.234Z",
  "response": {
    "image": {
      "media_type": "image",
      "url": "https://storage.cdn-luma.com/...",
      "width": 1024,
      "height": 1024
    }
  },
  "credits": {
    "dm_usage": 5,
    "dm_relaxed_usage": null
  }
}
```

**Failed:**

```json
{
  "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "type": "video",
  "status": "failed",
  "created": "2026-03-26T14:05:30.123Z",
  "updated": "2026-03-26T14:08:00.000Z",
  "response": null,
  "credits": null
}
```

{% endtab %}

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid job ID format.

```json
{
  "error": "Invalid jobid"
}
```
{% endtab %}

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

Job does not belong to this user.

```json
{
  "error": "Job does not belong to this user"
}
```
{% endtab %}

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found. The generation ID may be invalid or the account may have been removed.

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

{% tab v1_get_luma_jobs_jobid_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

Account session expired and could not be refreshed. Re-add the account using [POST /accounts](https://useapi.net/docs/api-luma-v1/post-luma-accounts).

```json
{
  "error": "Luma account has an error. Please check your account configuration via GET /v1/luma/accounts or re-add the account via POST /v1/luma/accounts",
  "code": 596
}
```
{% endtab %}

{% endtabs %}

### Model

{% tabs v1_get_luma_jobs_jobid_model %}

{% tab v1_get_luma_jobs_jobid_model Completed Video %}

Video generation completed. Includes video URL and metadata.

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'video'                    // Job type
  status: 'completed'
  created: string                  // ISO 8601 timestamp
  updated: string                  // ISO 8601 timestamp

  response: {
    video: {
      media_type: 'video'          // Media type
      url: string                  // Direct video URL (MP4)
      width: number                // Video width in pixels
      height: number               // Video height in pixels
      duration: number             // Video duration in seconds
    } | null
    video_hdr_exr: {               // HDR EXR version (if dynamic_range is "hdr_exr")
      media_type: 'video'
      url: string
      width: number
      height: number
      duration: number
    } | null
    thumbnail: {
      media_type: 'image'          // Media type
      url: string                  // Thumbnail image URL
      width: number
      height: number
    } | null
    last_frame: {
      media_type: 'image'          // Media type
      url: string                  // Last frame image URL
      width: number
      height: number
    } | null
  }

  credits: {
    dm_usage: number | null        // Credit cost
    dm_relaxed_usage?: number | null
  }
}
```

{% endtab %}

{% tab v1_get_luma_jobs_jobid_model Completed Image %}

Image generation completed. Includes image URL and metadata.

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

  response: {
    image: {
      media_type: 'image'          // Media type
      url: string                  // Direct image URL
      width: number                // Image width in pixels
      height: number               // Image height in pixels
    } | null
  }

  credits: {
    dm_usage: number | null        // Credit cost
    dm_relaxed_usage?: number | null
  }
}
```

{% endtab %}

{% tab v1_get_luma_jobs_jobid_model Failed %}

Generation failed. Includes error details.

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

  response: null
  credits: null
}
```

{% endtab %}

{% endtabs %}

### Webhook Callbacks

The `replyUrl` webhook callbacks from [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos) and [POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images) use the same response shape as this endpoint, with an additional `replyRef` field.

**Video callback:** single job result (same shape as above) + `replyRef`.

**Image callback:** wraps multiple job results in an `images` array:
```typescript
{
  jobid: string                    // Primary job ID
  type: 'image'
  status: 'completed' | 'failed'  // 'completed' if any image in batch succeeded
  images: Array</* same shape as single job result above */>
  replyRef?: string
}
```

**Error callback** (on exception):
```typescript
{
  jobid?: string
  status: 'failed'
  error: string
  replyRef?: string
}
```

### Examples

{% tabs v1_get_luma_jobs_jobid_examples %}

{% tab v1_get_luma_jobs_jobid_examples Curl %}
```bash
# Get job status
curl "https://api.useapi.net/v1/luma/jobs/j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Poll for completion (check every 10 seconds)
while true; do
  RESULT=$(curl -s "https://api.useapi.net/v1/luma/jobs/$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.video.url'
    break
  fi

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

  sleep 10
done
```
{% endtab %}

{% tab v1_get_luma_jobs_jobid_examples JavaScript %}
```javascript
const apiToken = 'YOUR_API_TOKEN'
const jobId = 'j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma'

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

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

    if (job.status === 'completed') {
      if (job.type === 'video') {
        console.log('Video URL:', job.response.video.url)
        console.log('Dimensions:', `${job.response.video.width}x${job.response.video.height}`)
      } else {
        console.log('Image URL:', job.response.image.url)
        console.log('Dimensions:', `${job.response.image.width}x${job.response.image.height}`)
      }
      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)
```
{% endtab %}

{% tab v1_get_luma_jobs_jobid_examples Python %}
```python
import requests
import time

api_token = 'YOUR_API_TOKEN'
job_id = 'j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma'

def get_job_status(job_id: str) -> dict:
    response = requests.get(
        f'https://api.useapi.net/v1/luma/jobs/{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':
            if job['type'] == 'video':
                print(f"Video URL: {job['response']['video']['url']}")
                print(f"Dimensions: {job['response']['video']['width']}x{job['response']['video']['height']}")

                # Download video
                video_response = requests.get(job['response']['video']['url'])
                with open('output.mp4', 'wb') as f:
                    f.write(video_response.content)
                print('Video saved to output.mp4')
            else:
                print(f"Image URL: {job['response']['image']['url']}")

            return job

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

        time.sleep(interval_sec)

job = wait_for_completion(job_id)
```
{% endtab %}

{% endtabs %}


### Try It

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

    mediaContainer.innerHTML = '';

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

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

    mediaContainer.style.display = 'none';
  }

  async function apiExecuteGetLumaJobsJobId() {
    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/luma/jobs/${jobidElement.value}`,
      elementId,
      data
    );

    if (status === 200) {
      try {
        const content = document.getElementById(`${elementId}-response-json`);
        const response = JSON.parse(content.innerText);
        displayLumaJobMedia(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="https://useapi.net/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="apiExecuteGetLumaJobsJobId()">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-luma-v1/get-luma-jobs ===
Document URL: https://useapi.net/docs/api-luma-v1/get-luma-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs
parent: Luma API v1
nav_order: 850
---
## List Executing Jobs
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all currently executing jobs for the authenticated user. Returns jobs that are in `created` or processing state.

{: .get }
> **https://api.useapi.net/v1/luma/jobs**

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

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

### Responses

{% tabs v1_get_luma_jobs_response %}

{% tab v1_get_luma_jobs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Returns the list of executing jobs.

```json
{
  "executing": 2,
  "jobs": [
    {
      "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
      "type": "video",
      "account": "user@example.com",
      "model": "ray-v3-flash",
      "created": "2026-03-26T14:05:30.123Z"
    },
    {
      "jobid": "j0326140730987654321i-u12345-email:user@example.com-gen:b2c3d4e5-f6a7-8901-bcde-f23456789012-bot:luma",
      "type": "image",
      "account": "user@example.com",
      "model": "photon-v2",
      "created": "2026-03-26T14:07:30.456Z"
    }
  ]
}
```

- `executing` - Total number of currently executing jobs.
- `jobs` - Array of executing job summaries.
  - `jobid` - Unique job identifier.
  - `type` - Job type (`video` or `image`).
  - `account` - Account email used for the job.
  - `model` - Model used for the job.
  - `created` - ISO 8601 timestamp of job creation.

{% endtab %}

{% tab v1_get_luma_jobs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

### Model

```typescript
{
  executing: number                // Total executing job count
  jobs: Array<{
    jobid: string                  // Unique job identifier
    type: 'video' | 'image'       // Job type
    account: string                // Account email
    model: string                  // Model name
    created: string                // ISO 8601 timestamp
    replyUrl?: 'configured'        // Present if webhook was set
  }>
  error?: string                   // Error message
}
```

### Examples

{% tabs v1_get_luma_jobs_example %}

{% tab v1_get_luma_jobs_example Curl %}
```bash
curl "https://api.useapi.net/v1/luma/jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
{% endtab %}

{% tab v1_get_luma_jobs_example JavaScript %}
```javascript
const token = 'YOUR_API_TOKEN'

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

const result = await response.json()
console.log(`Executing: ${result.executing} jobs`)
result.jobs.forEach(job => {
  console.log(`  ${job.jobid} (${job.type}, ${job.model})`)
})
```
{% endtab %}

{% tab v1_get_luma_jobs_example Python %}
```python
import requests

token = 'YOUR_API_TOKEN'

response = requests.get(
    'https://api.useapi.net/v1/luma/jobs',
    headers={'Authorization': f'Bearer {token}'}
)

result = response.json()
print(f"Executing: {result['executing']} jobs")
for job in result['jobs']:
    print(f"  {job['jobid']} ({job['type']}, {job['model']})")
```
{% endtab %}

{% endtabs %}

### Try It

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

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

    await apiExecute('https://api.useapi.net/v1/luma/jobs', 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="https://useapi.net/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="apiExecuteGetLumaJobs()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/index ===
Document URL: https://useapi.net/docs/api-luma-v1/index
---
layout: default
title: Luma API v1
nav_order: 2200
has_children: true
permalink: /docs/api-luma-v1
nav_exclude: true
---

# <img style="height:1.5em;vertical-align: middle;" src="https://useapi.net/assets/images/luma.svg"> Luma API v1
<small>April 6, 2026</small>

This is the [experimental](../../docs/legal) API for [Luma Dream Machine](https://lumalabs.ai/dream-machine) by [Luma AI](https://lumalabs.ai/).

[Luma Dream Machine](https://lumalabs.ai/dream-machine) creates AI-generated videos and images using Luma's proprietary models.

| Parameter | Video ([POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos)) | Image ([POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images)) |
|-----------|-------|-------|
| **Models** | `ray-v3-flash` (default), `ray-v3`, `ray-v3-reasoning` | `photon-v2` (default), `image-v2` |
| **Aspect ratios** | `9:16`, `3:4`, `1:1`, `4:3`, `16:9` (default), `21:9` | same |
| **Resolutions** | `draft` (default), `540p`, `720p`, `1080p` | `720p` (default), `1080p` |
| **Durations** | `5s` (default), `10s` | — |
| **Dynamic ranges** | `sdr` (default), `hdr`, `hdr_exr` | — |
| **Keyframes** | `imageStart`, `imageEnd` via [POST /assets](https://useapi.net/docs/api-luma-v1/post-luma-assets) | — |
| **Character ref** | `imageCharacter` (`ray-v3` + `sdr` only) | — |
| **Image refs** | — | `imageRef1..4` (up to 4, `image-v2` locked to 720p) |

**Cost estimate ([Luma Unlimited](https://lumalabs.ai/dream-machine) subscription):**
- Unlimited plan ($99.99/mo): unlimited generations at all resolutions and durations.

⚙️ [Setup Luma](../../docs/start-here/setup-luma)

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

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

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


=== URL: https://useapi.net/docs/api-luma-v1/post-luma-accounts ===
Document URL: https://useapi.net/docs/api-luma-v1/post-luma-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Luma API v1
nav_order: 200
---
## Configure Luma Account
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Configure your Luma account for API access using a `session` cookie. See [Setup Luma](../start-here/setup-luma) for details.

{: .post }
> **https://api.useapi.net/v1/luma/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](../start-here/setup-useapi) for details.

### Request Body
```json
{
  "session": "mK8jP2xZc9AfQw3LnT7vYbE1R"
}
```

- `session` is **required**. The `session` cookie value extracted from your browser during login. See [Setup Luma](../start-here/setup-luma) for instructions.
### Responses

{% tabs v1_post_luma_accounts_response %}

{% tab v1_post_luma_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Account configured successfully.

```json
{
  "account": "user@example.com",
  "user_id": "9ecac364-4b63-5b61-9241-297345710d63",
  "concurrency": 4,
  "luma_session_expires": "2026-05-27 00:28:17 UTC",
  "credits": { "usage": 20, "limit": 10000 },
  "created": true
}
```

{% endtab %}

{% tab v1_post_luma_accounts_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error (missing/invalid parameters).

```json
{
  "error": "Parameter session is required"
}
```
{% endtab %}

{% tab v1_post_luma_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_luma_accounts_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_luma_accounts_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

Session refreshed but upstream validation failed, or project creation failed.

```json
{
  "error": "Session refreshed but validation failed. Please try again."
}
```
{% endtab %}

{% endtabs %}

### Model

- `account` - Luma account email
- `user_id` - Luma user UUID
- `concurrency` - Account concurrency limit
- `luma_session_expires` - Session expiry (UTC datetime)
- `credits` - Credit usage (null if unavailable)
- `created` - `true` if new account, `false` if updated

```typescript
{ // TypeScript, all fields are optional
  account: string                // "user@example.com"
  user_id: string                // Luma user UUID
  concurrency: number            // Account concurrency limit
  luma_session_expires: string   // "2026-05-27 00:28:17 UTC"
  credits: {                     // Credit usage, null if unavailable
    usage: number
    limit: number
  } | null
  created: boolean               // true if new account, false if updated
  error?: string                 // Error message if any
}
```

### Examples

{% tabs v1_post_luma_accounts_example %}

{% tab v1_post_luma_accounts_example 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/luma/accounts" \
     -d '{
       "session": "mK8jP2xZc9AfQw3LnT7vYbE1R"
     }'
```
{% endtab %}

{% tab v1_post_luma_accounts_example JavaScript %}
``` javascript
const apiUrl = 'https://api.useapi.net/v1/luma/accounts';
const token = 'YOUR_API_TOKEN';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    session: 'mK8jP2xZc9AfQw3LnT7vYbE1R'
  })
});

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

{% tab v1_post_luma_accounts_example Python %}
``` python
import requests

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

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

body = {
    'session': 'mK8jP2xZc9AfQw3LnT7vYbE1R'
}

response = requests.post(apiUrl, headers=headers, json=body)
print(response.status_code, response.json())
```
{% endtab %}

{% endtabs %}

### Try It

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

      const body = { session: document.getElementById('post-accounts-Luma-session')?.value?.trim() };
      data.body = JSON.stringify(body);

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

<form id="post-accounts-Luma" onsubmit="return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-Luma-api_token"><span>API Token<small> (see <a href="https://useapi.net/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-Luma-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-Luma-session"><span>session<small> (session cookie — see <a href="https://useapi.net/docs/start-here/setup-luma">Setup Luma</a>)</small></span>
        <input id="post-accounts-Luma-session" type="text" class="input-element" required aria-required="true">
      </label>
    </div>
    <button id="post-accounts-Luma-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestAccountLuma()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/post-luma-assets ===
Document URL: https://useapi.net/docs/api-luma-v1/post-luma-assets
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/<code class="language-plaintext highlighter-rouge">email</code>
parent: Luma API v1
nav_order: 500
---
## Upload Assets
{: .no_toc }

<small>April 6, 2026</small>



## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Upload images to Luma CDN for use in video generation (keyframes, character reference) and image generation (style/character references). Supported formats are JPEG, PNG, and WebP with a maximum file size of 20 MB.

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

The returned `assetRef` is used as `imageStart`, `imageEnd`, or `imageCharacter` in [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos), and as `imageRef1..4` in [POST /images](https://useapi.net/docs/api-luma-v1/post-luma-images).

Assets are stored for 30 days.

{: .post }
> **https://api.useapi.net/v1/luma/assets/`email`**

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

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

### Path Parameters

- `email` is **required**, the Luma account email address.

### Request Body

Binary image content (raw bytes).

### Responses

{% tabs v1_post_luma_assets_response %}

{% tab v1_post_luma_assets_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Image uploaded successfully. Returns the `assetRef` for use in video generation.

```json
{
  "assetRef": "u12345-email:user@example.com-image:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "user@example.com",
  "upload": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "media": {
      "url": "https://storage.cdn-luma.com/uploads/..."
    }
  }
}
```

- `assetRef` - Reference ID for use in [POST /videos](https://useapi.net/docs/api-luma-v1/post-luma-videos) as the `image` parameter.
- `email` - Account used for the upload.
- `upload.id` - Luma upload identifier.
- `upload.media.url` - CDN URL of the uploaded image.

**assetRef format:** `u{userid}-email:{email}-image:{uuid}`

{% endtab %}

{% tab v1_post_luma_assets_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request (empty content, unsupported content type, or file too large).

```json
{
  "error": "Content-Type (image/bmp) not supported. Valid: image/jpeg, image/png, image/webp"
}
```

```json
{
  "error": "Content is empty"
}
```
{% endtab %}

{% tab v1_post_luma_assets_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_luma_assets_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account not found or not configured.

```json
{
  "error": "Unable to find configuration for email user@example.com"
}
```
{% endtab %}

{% tab v1_post_luma_assets_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

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

```json
{
  "error": "Luma account has an error. Please check your account configuration via GET /v1/luma/accounts or re-add the account via POST /v1/luma/accounts"
}
```
{% endtab %}

{% endtabs %}

### Model
```typescript
{
  assetRef: string                // Reference ID for POST /videos image param
  email: string                   // "user@example.com"
  upload: {
    id: string                    // Luma upload UUID
    media: {
      url: string                 // CDN URL of uploaded image
    }
  }
  error?: string                  // Error message
}
```

### Examples

{% tabs v1_post_luma_assets_example %}

{% tab v1_post_luma_assets_example 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/luma/assets/user@example.com"
```
{% endtab %}

{% tab v1_post_luma_assets_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN'
const email = 'user@example.com'

const apiUrl = `https://api.useapi.net/v1/luma/assets/${encodeURIComponent(email)}`

// 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)
```
{% endtab %}

{% tab v1_post_luma_assets_example Python %}
``` python
import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
email = 'user@example.com'

api_url = f'https://api.useapi.net/v1/luma/assets/{quote(email, 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'))
```
{% endtab %}

{% endtabs %}


### Try It

<script>
  async function apiExecutePostLumaAssetEmail() {
    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/luma/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="https://useapi.net/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="user@example.com">
      </label>
      <label for="input-file"><span>Upload file</span>
        <div style="display:flex">
          <button id="input-file-clear" onclick="clearInputFile()">&#10006;</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="apiExecutePostLumaAssetEmail()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/post-luma-images ===
Document URL: https://useapi.net/docs/api-luma-v1/post-luma-images
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images
parent: Luma API v1
nav_order: 700
---
## Generate Images
{: .no_toc }

<small>April 6, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Generate images using Luma AI models from text prompts. Each request produces a batch of 4 images. All image generation is asynchronous — this endpoint returns immediately with job IDs. Poll [GET /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid) for completion, or use `replyUrl` webhook for automatic callbacks.

Each image batch uses **1 concurrency slot** regardless of the number of images (4) in the batch.

Image generation typically completes within 30-60 seconds depending on the model and resolution.

### Model Compatibility Matrix

| | `photon-v2` (default) | `image-v2` |
|---|---|---|
| **Resolutions** | 720p, 1080p | 720p, 1080p |
| **Image references** | up to 4, all resolutions | up to 4, **720p only** |

{: .post }
> **https://api.useapi.net/v1/luma/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](../start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A photorealistic portrait of an astronaut on Mars",
  "model": "photon-v2",
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}
```

- `prompt` is **required**. Text description of the images to generate. Maximum 2000 characters.
- `email` is optional. Specific account to use. Auto-selected (random with available capacity) if omitted. When `imageRef1..4` is provided, the account is automatically inferred from the asset reference — `email` is not required. If provided, it must match the asset's account. All references must belong to the same account.
- `model` is optional, the AI model to use (default: `photon-v2`). Supported values: `photon-v2`, `image-v2`.
- `resolution` is optional, image resolution (default: `720p`). Supported values: `720p`, `1080p`. When using `image-v2` with references, resolution is locked to `720p`.
- `aspect_ratio` is optional, image aspect ratio (default: `16:9`). Supported values: `9:16`, `3:4`, `1:1`, `4:3`, `16:9`, `21:9`.
- `imageRef1` is optional. `assetRef` from [POST /assets/`email`](https://useapi.net/docs/api-luma-v1/post-luma-assets) — reference image for style/character guidance.
- `imageRef2`, `imageRef3`, `imageRef4` are optional. Additional reference images (up to 4 total).
- `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with the job record on submission and on completion/failure.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.


### Responses

{% tabs v1_post_luma_images_response %}

{% tab v1_post_luma_images_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Job created successfully. A batch of 4 images is generating in the background.

```json
{
  "jobid": "j0326140530123456789i-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "jobids": [
    "j0326140530123456789i-u12345-email:user@example.com-gen:b2c3d4e5-f6a7-8901-bcde-f23456789012-bot:luma",
    "j0326140530123456789i-u12345-email:user@example.com-gen:c3d4e5f6-a7b8-9012-cdef-345678901234-bot:luma",
    "j0326140530123456789i-u12345-email:user@example.com-gen:d4e5f6a7-b890-1234-defa-456789012345-bot:luma",
    "j0326140530123456789i-u12345-email:user@example.com-gen:e5f6a7b8-9012-3456-efab-567890123456-bot:luma"
  ],
  "type": "image",
  "status": "created",
  "count": 4,
  "created": "2026-03-26T14:05:30.123Z",
  "request": {
    "prompt": "A photorealistic portrait of an astronaut on Mars",
    "model": "photon-v2",
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}
```

- `jobid` - Primary job identifier (parent job).
- `jobids` - Array of 4 individual image job IDs. Poll each via [GET /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid).
- `count` - Number of images in the batch (always 4).

Poll [GET /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid) for each individual image job, or use `replyUrl` for webhook callbacks.

{% endtab %}

{% tab v1_post_luma_images_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

```json
{
  "error": "Parameter model (invalid-model) valid values: photon-v2, image-v2"
}
```
{% endtab %}

{% tab v1_post_luma_images_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_luma_images_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_luma_images_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Entity</span></a>

Content moderation rejection.

```json
{
  "error": "Content moderation: prompt rejected",
  "code": 422
}
```
{% endtab %}

{% tab v1_post_luma_images_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

All accounts at maximum capacity. Wait for current jobs to complete or use [DELETE /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/delete-luma-jobs-jobid) to free slots.

```json
{
  "error": "All configured accounts are running at maximum capacity",
  "code": 429
}
```
{% endtab %}

{% tab v1_post_luma_images_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

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

```json
{
  "error": "Luma account has an error. Please check your account configuration via GET /v1/luma/accounts or re-add the account via POST /v1/luma/accounts"
}
```
{% endtab %}

{% endtabs %}

### Model

```typescript
{
  jobid: string                    // Primary job identifier
  jobids: string[]                 // Array of 4 individual image job IDs
  type: 'image'                    // Job type
  status: 'created'                // Initial status
  count: 4                         // Number of images in batch
  created: string                  // ISO 8601 timestamp
  request: {
    prompt: string
    model: string                  // "photon-v2" | "image-v2"
    resolution?: string            // "720p" | "1080p"
    aspect_ratio?: string          // "9:16" | "3:4" | "1:1" | "4:3" | "16:9" | "21:9"
    imageRefs?: string[]           // Array of assetRef IDs (when references provided)
  }
}
```

### Webhook Callback (`replyUrl`)

When `replyUrl` is provided, the API sends a POST request to that URL on completion or failure. The callback wraps individual image results in an `images` array — overall status is `completed` if **any** image in the batch succeeded. See [Webhook Callbacks](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid#webhook-callbacks) for full type definitions.

### Examples

{% tabs v1_post_luma_images_example %}

{% tab v1_post_luma_images_example Curl %}
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A photorealistic portrait of an astronaut on Mars",
       "model": "photon-v2",
       "resolution": "1080p",
       "aspect_ratio": "16:9"
     }' \
     "https://api.useapi.net/v1/luma/images"
```
{% endtab %}

{% tab v1_post_luma_images_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN'
const apiUrl = 'https://api.useapi.net/v1/luma/images'

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A photorealistic portrait of an astronaut on Mars',
    model: 'photon-v2',
    resolution: '1080p',
    aspect_ratio: '16:9'
  })
})

const result = await response.json()
console.log('Batch created:', result.jobid)
console.log('Image jobs:', result.jobids)

// Poll each image job for completion
const pollJob = async (jobid) => {
  while (true) {
    const res = await fetch(`https://api.useapi.net/v1/luma/jobs/${jobid}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    })
    const job = await res.json()

    if (job.status === 'completed') {
      console.log('Image URL:', job.response.image.url)
      return job
    }
    if (job.status === 'failed') throw new Error(job.error)

    await new Promise(r => setTimeout(r, 5000))
  }
}

const images = await Promise.all(result.jobids.map(pollJob))
```
{% endtab %}

{% tab v1_post_luma_images_example Python %}
``` python
import requests
import time

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

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

data = {
    'prompt': 'A photorealistic portrait of an astronaut on Mars',
    'model': 'photon-v2',
    'resolution': '1080p',
    'aspect_ratio': '16:9'
}

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

# Poll each image job for completion
for jobid in result['jobids']:
    while True:
        job = requests.get(
            f'https://api.useapi.net/v1/luma/jobs/{jobid}',
            headers={'Authorization': f'Bearer {token}'}
        ).json()
        print(f"Job {jobid}: {job['status']}")

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

        time.sleep(5)
```
{% endtab %}

{% endtabs %}

### Try It

<script>
  async function apiExecutePostLumaImages() {
    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)
    };

    await apiExecute('https://api.useapi.net/v1/luma/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="https://useapi.net/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="user@example.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A photorealistic portrait of an astronaut on Mars">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="photon-v2">photon-v2 (default)</option>
          <option value="image-v2">image-v2</option>
        </select>
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="720p">720p (default)</option>
          <option value="1080p">1080p</option>
        </select>
      </label>
      <label for="input-aspect_ratio"><span>aspect_ratio</span>
        <select id="input-aspect_ratio" class="input-element input-query-param">
          <option value="16:9">16:9 (default)</option>
          <option value="9:16">9:16</option>
          <option value="3:4">3:4</option>
          <option value="1:1">1:1</option>
          <option value="4:3">4:3</option>
          <option value="21:9">21:9</option>
        </select>
      </label>
      <label for="input-imageRef1"><span>imageRef1<small> (reference image, assetRef from <a href="https://useapi.net/docs/api-luma-v1/post-luma-assets">POST /assets</a>)</small></span>
        <input id="input-imageRef1" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-imageRef2"><span>imageRef2<small> (optional)</small></span>
        <input id="input-imageRef2" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-imageRef3"><span>imageRef3<small> (optional)</small></span>
        <input id="input-imageRef3" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-imageRef4"><span>imageRef4<small> (optional)</small></span>
        <input id="input-imageRef4" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </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="apiExecutePostLumaImages()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/api-luma-v1/post-luma-videos ===
Document URL: https://useapi.net/docs/api-luma-v1/post-luma-videos
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos
parent: Luma API v1
nav_order: 600
---
## Generate Videos
{: .no_toc }

<small>April 6, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

Video generation typically completes within 30-60 seconds for draft, and ~3 minutes for 1080p on unlimited plans (relaxed mode). Generation times vary by model, resolution, and server load.

### Model Compatibility Matrix

Not all parameter combinations are supported. The API validates against this matrix and returns `400` for unsupported combinations.

| | `ray-v3-flash` (default) | `ray-v3` | `ray-v3-reasoning` |
|---|---|---|---|
| **Resolutions** | draft, 540p, 720p, 1080p | draft, 540p, 720p, 1080p | 720p, 1080p |
| **Durations** | 5s, 10s | 5s, 10s | 5s, 10s |
| **SDR** | all resolutions, 5s+10s | all resolutions, 5s+10s | all resolutions, 5s+10s |
| **HDR** | 540p-1080p, 5s only | 540p-1080p, 5s only | 720p-1080p, 5s only |
| **HDR+EXR** | 540p-720p, 5s only | 540p-720p, 5s only | 720p only, 5s only |
| **imageStart/imageEnd** | yes | yes | yes |
| **imageCharacter** | no | **yes** (SDR only) | no |

**Dynamic range output formats:**
- **`sdr`** — Standard H.264 MP4 (playable in browsers).
- **`hdr`** — HEVC (H.265) Main 10 profile, BT.2020 color, HDR10 (PQ). **Not playable in browsers** — requires VLC, mpv, or a native HDR-capable player.
- **`hdr_exr`** — Same HDR video + EXR frames download (ZIP) available via `response.video_hdr_exr`.

{: .post }
> **https://api.useapi.net/v1/luma/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](../start-here/setup-useapi) for details.

### Request Body

```json
{
  "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
  "model": "ray-v3-flash",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": "5s"
}
```

- `prompt` is **required**. Text description of the video to generate. Maximum 2000 characters.
- `email` is optional. Specific account to use. Auto-selected (random with available capacity) if omitted. When `imageStart`, `imageEnd`, or `imageCharacter` is provided, the account is automatically inferred from the asset reference — `email` is not required. If provided, it must match the asset's account.
- `model` is optional, the AI model to use (default: `ray-v3-flash`). Supported values: `ray-v3-flash`, `ray-v3`, `ray-v3-reasoning`.
- `resolution` is optional, video resolution (default: `draft`). Supported values: `draft`, `540p`, `720p`, `1080p`. See matrix above for per-model restrictions.
- `aspect_ratio` is optional, video aspect ratio (default: `16:9`). Supported values: `9:16`, `3:4`, `1:1`, `4:3`, `16:9`, `21:9`.
- `duration` is optional, video duration (default: `5s`). Supported values: `5s`, `10s`. HDR/HDR+EXR limited to `5s`.
- `dynamic_range` is optional, video dynamic range (default: `sdr`). Supported values: `sdr`, `hdr`, `hdr_exr`. See matrix above for resolution restrictions and output format details.
- `imageStart` is optional. `assetRef` from [POST /assets/`email`](https://useapi.net/docs/api-luma-v1/post-luma-assets) — start keyframe for image-to-video.
- `imageEnd` is optional. `assetRef` — end keyframe. Can be used alone or with `imageStart`.
- `imageCharacter` is optional. `assetRef` — character reference image. Only supported with `ray-v3` model and `sdr` dynamic range. **Cannot** be combined with `imageStart` or `imageEnd`.
- `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with the job record on submission and on completion/failure.
- `replyRef` is optional, custom reference string passed back in webhook callbacks.


### Responses

{% tabs v1_post_luma_videos_response %}

{% tab v1_post_luma_videos_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Job created successfully. Video is generating in the background.

```json
{
  "jobid": "j0326140530123456789v-u12345-email:user@example.com-gen:a1b2c3d4-e5f6-7890-abcd-ef1234567890-bot:luma",
  "type": "video",
  "status": "created",
  "created": "2026-03-26T14:05:30.123Z",
  "request": {
    "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
    "model": "ray-v3-flash",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s",
    "dynamic_range": "sdr"
  }
}
```

Poll [GET /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid) for completion status, or use `replyUrl` for webhook callbacks.

{% endtab %}

{% tab v1_post_luma_videos_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

```json
{
  "error": "Parameter model (invalid-model) valid values: ray-v3-flash, ray-v3, ray-v3-reasoning"
}
```
{% endtab %}

{% tab v1_post_luma_videos_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v1_post_luma_videos_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v1_post_luma_videos_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Asset not found or expired.

```json
{
  "error": "Asset not found"
}
```
{% endtab %}

{% tab v1_post_luma_videos_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Entity</span></a>

Content moderation rejection.

```json
{
  "error": "Content moderation: prompt rejected",
  "code": 422
}
```
{% endtab %}

{% tab v1_post_luma_videos_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

All accounts at maximum capacity. Wait for current jobs to complete or use [DELETE /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/delete-luma-jobs-jobid) to free slots.

```json
{
  "error": "All configured accounts are running at maximum capacity",
  "code": 429
}
```
{% endtab %}

{% tab v1_post_luma_videos_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Session Error</span></a>

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

```json
{
  "error": "Luma account has an error. Please check your account configuration via GET /v1/luma/accounts or re-add the account via POST /v1/luma/accounts"
}
```
{% endtab %}

{% endtabs %}

### Model

```typescript
{
  jobid: string                    // Unique job identifier
  type: 'video'                    // Job type
  status: 'created'                // Initial status
  created: string                  // ISO 8601 timestamp
  request: {
    prompt: string
    model: string                  // "ray-v3-flash" | "ray-v3" | "ray-v3-reasoning"
    imageStart?: string            // assetRef — start keyframe
    imageEnd?: string              // assetRef — end keyframe
    imageCharacter?: string        // assetRef — character reference (ray-v3 + sdr only)
    resolution?: string            // "draft" | "540p" | "720p" | "1080p"
    aspect_ratio?: string          // "9:16" | "3:4" | "1:1" | "4:3" | "16:9" | "21:9"
    duration?: string              // "5s" | "10s"
    dynamic_range?: string         // "sdr" | "hdr" | "hdr_exr"
  }
}
```

### Webhook Callback (`replyUrl`)

When `replyUrl` is provided, the API sends a POST request to that URL on completion or failure. The callback payload uses the same shape as [GET /jobs/`jobid`](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid) with an additional `replyRef` field. See [Webhook Callbacks](https://useapi.net/docs/api-luma-v1/get-luma-jobs-jobid#webhook-callbacks) for full type definitions.

### Examples

{% tabs v1_post_luma_videos_example %}

{% tab v1_post_luma_videos_example 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": "ray-v3-flash",
       "resolution": "720p",
       "aspect_ratio": "16:9",
       "duration": "5s"
     }' \
     "https://api.useapi.net/v1/luma/videos"

# Image-to-video
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "Camera slowly pans across the scene",
       "model": "ray-v3",
       "imageStart": "u12345-email:user@example.com-image:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "resolution": "1080p",
       "duration": "5s"
     }' \
     "https://api.useapi.net/v1/luma/videos"
```
{% endtab %}

{% tab v1_post_luma_videos_example JavaScript %}
``` javascript
const token = 'YOUR_API_TOKEN'
const apiUrl = 'https://api.useapi.net/v1/luma/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: 'ray-v3-flash',
    resolution: '720p',
    aspect_ratio: '16:9',
    duration: '5s'
  })
})

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/luma/jobs/${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.video.url)
      return job
    }
    if (job.status === 'failed') throw new Error(job.error)

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

const completed = await poll(result.jobid)
```
{% endtab %}

{% tab v1_post_luma_videos_example Python %}
``` python
import requests
import time

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

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

# Text-to-video
data = {
    'prompt': 'A serene mountain landscape at sunset',
    'model': 'ray-v3-flash',
    'resolution': '720p',
    'aspect_ratio': '16:9',
    'duration': '5s'
}

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/luma/jobs/{jobid}',
        headers={'Authorization': f'Bearer {token}'}
    ).json()
    print(f"Status: {job['status']}")

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

    time.sleep(10)
```
{% endtab %}

{% endtabs %}

### Try It

<script>
  async function apiExecutePostLumaVideos() {
    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)
    };

    await apiExecute('https://api.useapi.net/v1/luma/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="https://useapi.net/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="user@example.com">
      </label>
      <label for="input-prompt"><span>prompt<small> (required)</small></span>
        <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A serene mountain landscape at sunset">
      </label>
      <label for="input-imageStart"><span>imageStart<small> (start keyframe, assetRef from <a href="https://useapi.net/docs/api-luma-v1/post-luma-assets">POST /assets</a>)</small></span>
        <input id="input-imageStart" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-imageEnd"><span>imageEnd<small> (end keyframe)</small></span>
        <input id="input-imageEnd" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-imageCharacter"><span>imageCharacter<small> (character ref, ray-v3 + sdr only)</small></span>
        <input id="input-imageCharacter" type="text" class="input-element input-query-param" placeholder="u12345-email:user@example.com-image:...">
      </label>
      <label for="input-model"><span>model</span>
        <select id="input-model" class="input-element input-query-param">
          <option value="ray-v3-flash">ray-v3-flash (default)</option>
          <option value="ray-v3">ray-v3</option>
          <option value="ray-v3-reasoning">ray-v3-reasoning</option>
        </select>
      </label>
      <label for="input-resolution"><span>resolution</span>
        <select id="input-resolution" class="input-element input-query-param">
          <option value="draft">draft (default)</option>
          <option value="540p">540p</option>
          <option value="720p">720p</option>
          <option value="1080p">1080p</option>
        </select>
      </label>
      <label for="input-aspect_ratio"><span>aspect_ratio</span>
        <select id="input-aspect_ratio" class="input-element input-query-param">
          <option value="16:9">16:9 (default)</option>
          <option value="9:16">9:16</option>
          <option value="3:4">3:4</option>
          <option value="1:1">1:1</option>
          <option value="4:3">4:3</option>
          <option value="21:9">21:9</option>
        </select>
      </label>
      <label for="input-duration"><span>duration</span>
        <select id="input-duration" class="input-element input-query-param">
          <option value="5s">5s (default)</option>
          <option value="10s">10s</option>
        </select>
      </label>
      <label for="input-dynamic_range"><span>dynamic_range</span>
        <select id="input-dynamic_range" class="input-element input-query-param">
          <option value="sdr">sdr (default)</option>
          <option value="hdr">hdr</option>
          <option value="hdr_exr">hdr_exr</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="apiExecutePostLumaVideos()">Go</button>
  </div>
</form>

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


=== URL: https://useapi.net/docs/start-here/setup-midjourney ===
Document URL: https://useapi.net/docs/start-here/setup-midjourney
---
layout: default
title: Setup Midjourney
parent: Start Here
nav_order: 200
---
# <img style="height:1.5em;vertical-align: middle;" src="https://useapi.net/assets/images/midjourney.svg"> Setup Midjourney
{: .no_toc }

<small>December 2023 (January 14, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 10 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [Midjourney API](../api-midjourney-v3). An active [Midjourney](https://www.midjourney.com) subscription and a [useapi.net subscription](../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](../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="https://useapi.net/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
---
layout: default
title: 🔓 CAPTCHA Solver
parent: Midjourney API v3
nav_order: 5000
---
# CAPTCHA Solver
{: .no_toc }

<small>December 8, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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](https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v3
nav_order: 400
---
## Delete Channel Configuration
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **https://api.useapi.net/v3/midjourney/accounts/`channel`**

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

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

### Path Parameters

- `channel` is **required**. The Discord channel ID to delete.

### Responses

{% tabs v3_delete_accounts_response %}

{% tab v3_delete_accounts_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>

Channel deleted successfully.

**No Content** (empty response body)

{% endtab %}

{% tab v3_delete_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_delete_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Channel not found or not configured.

**No Content** (empty response body)

{% endtab %}

{% endtabs %}

### Examples

{% tabs v3_delete_accounts_example %}

{% tab v3_delete_accounts_example Curl %}
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/1234567890123456789"
```
{% endtab %}

{% tab v3_delete_accounts_example 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);
}
```
{% endtab %}

{% tab v3_delete_accounts_example 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}')
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Midjourney API v3
nav_order: 1900
---
## Cancel Running Job
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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

{: .delete }
> **https://api.useapi.net/v3/midjourney/jobs/`jobid`**

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

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

### Path Parameters

- `jobid` is **required**. The job ID to cancel.

### Responses

{% tabs v3_delete_job_response %}

{% tab v3_delete_job_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>

Job cancelled successfully.

**No Content** (empty response body)

The job status has been updated to `failed` and removed from running jobs list.

{% endtab %}

{% tab v3_delete_job_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_delete_job_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found.

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

{% tab v3_delete_job_response <span class="http-status-bad">410</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

Job expired (older than 62 days).

```json
{
  "error": "Job j1023... has expired"
}
```
{% endtab %}

{% endtabs %}

### Examples

{% tabs v3_delete_job_example %}

{% tab v3_delete_job_example Curl %}
``` bash
curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney"
```
{% endtab %}

{% tab v3_delete_job_example 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);
}
```
{% endtab %}

{% tab v3_delete_job_example 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}')
```
{% endtab %}

{% endtabs %}

### 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
---
layout: default
title: 🎨 Live Demo
parent: Midjourney API v3
nav_order: 190
---

<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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v3
nav_order: 350
---
## Get Channel Configuration
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Get configuration details for a specific Midjourney channel.

{: .get }
> **https://api.useapi.net/v3/midjourney/accounts/`channel`**

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

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

### Path Parameters

- `channel` is **required**. The Discord channel ID to query.

### Responses

{% tabs v3_get_accounts_channel_response %}

{% tab v3_get_accounts_channel_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts-reset) to clear the error
- Check your Discord account for moderation messages or CAPTCHA challenges

{% endtab %}

{% tab v3_get_accounts_channel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_get_accounts_channel_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Channel not found or not configured.

**No Content** (empty response body)

{% endtab %}

{% endtabs %}

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

{% tabs v3_get_accounts_channel_example %}

{% tab v3_get_accounts_channel_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/1234567890123456789"
```
{% endtab %}

{% tab v3_get_accounts_channel_example 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);
```
{% endtab %}

{% tab v3_get_accounts_channel_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Midjourney API v3
nav_order: 300
---
## List All Configured Channels
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all configured Midjourney channels for your account.

**To get a specific channel:** Use [GET /accounts/:channel](https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts-channel).

{: .get }
> **https://api.useapi.net/v3/midjourney/accounts**

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

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

### Responses

{% tabs v3_get_accounts_response %}

{% tab v3_get_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts-reset) to clear the error
- Check your Discord account for moderation messages or CAPTCHA challenges

{% endtab %}

{% tab v3_get_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_get_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

No channels configured.

**No Content** (empty response body)

{% endtab %}

{% endtabs %}

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

{% tabs v3_get_accounts_example %}

{% tab v3_get_accounts_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts"
```
{% endtab %}

{% tab v3_get_accounts_example 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);
```
{% endtab %}

{% tab v3_get_accounts_example 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())
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Midjourney API v3
nav_order: 1800
---
## Retrieve Job Status and Results
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v3/midjourney/jobs/`jobid`**

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

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

### Path Parameters

- `jobid` is **required**. The job ID to query.

### Responses

{% tabs v3_get_job_response %}

{% tab v3_get_job_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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": {}
  }
}
```

{% endtab %}

{% tab v3_get_job_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_get_job_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_get_job_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found.

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

{% tab v3_get_job_response <span class="http-status-bad">410</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

Job expired (older than 62 days).

```json
{
  "error": "Job j1023... has expired"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs v3_get_job_example %}

{% tab v3_get_job_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs/j1023141520123456789i-u12345-c1234567890123456789-bot:midjourney"
```
{% endtab %}

{% tab v3_get_job_example 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);
```
{% endtab %}

{% tab v3_get_job_example 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'))
```
{% endtab %}

{% endtabs %}

### Try It

<script src="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs
parent: Midjourney API v3
nav_order: 1700
---
## List Running Jobs
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

List all currently running jobs for your account.

{: .get }
> **https://api.useapi.net/v3/midjourney/jobs**

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

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

### Responses

{% tabs v3_get_jobs_response %}

{% tab v3_get_jobs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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`](https://useapi.net/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"
        }
      ]
    }
  }
}
```

{% endtab %}

{% tab v3_get_jobs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs v3_get_jobs_example %}

{% tab v3_get_jobs_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/jobs"
```
{% endtab %}

{% tab v3_get_jobs_example 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})`);
  }
}
```
{% endtab %}

{% tab v3_get_jobs_example 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']})")
```
{% endtab %}

{% endtabs %}

### 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> proxy/cdn-midjourney
parent: Midjourney API v3
nav_order: 2300
---
## Proxy asset retrieval from https://cdn.midjourney.com
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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:

{% tabs  direct_cdn_access %}

{% tab  direct_cdn_access 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
```
{% endtab %}

{% tab  direct_cdn_access 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));
```
{% endtab %}

{% tab  direct_cdn_access 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)
```
{% endtab %}

{% endtabs %}

**Note:** The `User-Agent` header is critical—without it, Cloudflare will block your request.

---

{: .get }
> **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](../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

{% tabs proxy_cdn_midjourney_response %}

{% tab proxy_cdn_midjourney_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Returns the proxied content from the Midjourney CDN with appropriate headers.

{% endtab %}

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```

{% endtab %}

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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.

{% endtab %}

{% endtabs %}

##### Examples

{% tabs  get_proxy_cdn_midjourney_example %}

{% tab  get_proxy_cdn_midjourney_example Curl %}
``` bash
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=https://cdn.midjourney.com/example-image.jpg"
```
{% endtab %}

{% tab  get_proxy_cdn_midjourney_example 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});
```
{% endtab %}

{% tab  get_proxy_cdn_midjourney_example 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)
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-midjourney-v3/index ===
Document URL: https://useapi.net/docs/api-midjourney-v3/index
---
layout: default
title: Midjourney API v3
nav_order: 1000
has_children: true
permalink: /docs/api-midjourney-v3
---

# <img style="height:2em;vertical-align: middle;" src="https://useapi.net/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](https://useapi.net/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](https://useapi.net/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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/reset/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v3
nav_order: 500
---
## Reset Channel After Moderation
{: .no_toc }

<small>October 27, 2025 (March 3, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **https://api.useapi.net/v3/midjourney/accounts/reset/`channel`**

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

- `API token` is **required**, see [Setup useapi.net](../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](https://useapi.net/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

{% tabs v3_post_accounts_reset_response %}

{% tab v3_post_accounts_reset_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>

Error cleared successfully. Channel is ready for use.

**No Content** (empty response body)

{% endtab %}

{% tab v3_post_accounts_reset_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab v3_post_accounts_reset_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Channel not found or not configured.

**No Content** (empty response body)

{% endtab %}

{% tab v3_post_accounts_reset_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](https://useapi.net/docs/api-midjourney-v3/delete-midjourney-accounts-channel) and configure a new Discord account.

{% endtab %}

{% endtabs %}

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

### Examples

{% tabs v3_post_accounts_reset_example %}

{% tab v3_post_accounts_reset_example Curl %}
``` bash
curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v3/midjourney/accounts/reset/1234567890123456789"
```
{% endtab %}

{% tab v3_post_accounts_reset_example 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);
}
```
{% endtab %}

{% tab v3_post_accounts_reset_example 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}')
```
{% endtab %}

{% endtabs %}


### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Midjourney API v3
nav_order: 200
---
## Configure Midjourney Channel
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-midjourney-v3/quick-start#migration-from-v2) for details.

{: .post }
> **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](../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](../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.

### Responses

{% tabs v3_post_accounts_response %}

{% tab v3_post_accounts_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

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).
{% endtab %}

{% tab v3_post_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Existing channel configuration updated successfully.

```json
{
  "discord": "MTI...xyz",
  "channel": "1234567890123456789",
  "maxJobs": 5,
  "maxImageJobs": 5,
  "maxVideoJobs": 3,
  "replyUrl": "https://your-server.com/webhook"
}
```
{% endtab %}

{% tab v3_post_accounts_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error (missing/invalid parameters).

```json
{
  "error": "Required parameter discord is missing or empty"
}
```
{% endtab %}

{% tab v3_post_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token or Discord token.

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

{% tab v3_post_accounts_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

Subscription expired or insufficient credits.

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

{% tab v3_post_accounts_response <span class="http-status-bad">409</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409" rel="noreferrer" target="_blank"><span class="http-status-bad">409 Conflict</span></a>

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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs v3_post_accounts_example %}

{% tab v3_post_accounts_example 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"
     }'
```
{% endtab %}

{% tab v3_post_accounts_example 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);
```
{% endtab %}

{% tab v3_post_accounts_example 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())
```
{% endtab %}

{% endtabs %}

### 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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/blend
parent: Midjourney API v3
nav_order: 900
---
## Midjourney /blend Command
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Blend 2-5 images together using Midjourney's [/blend](https://docs.midjourney.com/docs/blend) command.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_blend_json_response %}

{% tab v3_post_blend_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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"
    }
}
```
{% endtab %}

{% tab v3_post_blend_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "At least 2 images are required for blend"
}
```

{% endtab %}

{% tab v3_post_blend_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_blend_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_blend_json_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

{% endtab %}

{% tab v3_post_blend_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_blend_example %}

{% tab v3_post_blend_example 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}'
```
{% endtab %}

{% tab v3_post_blend_example 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
```
{% endtab %}

{% tab v3_post_blend_example 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
```
{% endtab %}

{% endtabs %}

### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/button
parent: Midjourney API v3
nav_order: 700
---
## Execute Midjourney Buttons
{: .no_toc }

<small>October 27, 2025 (February 19, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../api-midjourney-v3/vary-region-mask-editor) for details.

- `prompt` is **optional**. Required for `Custom Zoom` button.
  When [Remix mode](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_button_json_response %}

{% tab v3_post_button_json_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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).
{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

New button job created.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "jobId is required"
}
```
{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_button_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_button_json_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

```json
{
  "error": "Parent job not found"
}
```
{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-bad">410</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

Parent job is older than 62 days.

```json
{
  "error": "Parent job has expired"
}
```

{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

{% endtab %}

{% tab v3_post_button_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_button_example %}

{% tab v3_post_button_example 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}'
```
{% endtab %}

{% tab v3_post_button_example 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
```
{% endtab %}

{% tab v3_post_button_example 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
```
{% endtab %}

{% endtabs %}

### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/describe
parent: Midjourney API v3
nav_order: 800
---
## Midjourney /describe Command
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Generate text prompts from an image using Midjourney's [/describe](https://docs.midjourney.com/docs/explore-prompting) command. Returns 4 prompt suggestions. 

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_describe_json_response %}

{% tab v3_post_describe_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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"
    }
}
```
{% endtab %}

{% tab v3_post_describe_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Either imageUrl or imageBlob is required"
}
```

{% endtab %}

{% tab v3_post_describe_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_describe_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_describe_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_describe_example %}

{% tab v3_post_describe_example 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"
```
{% endtab %}

{% tab v3_post_describe_example 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
```
{% endtab %}

{% tab v3_post_describe_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/fast
parent: Midjourney API v3
nav_order: 1200
---
## Switch to Fast Mode
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Switch Midjourney account to [Fast mode](https://docs.midjourney.com/docs/fast-mode) using the /fast command.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_fast_json_response %}

{% tab v3_post_fast_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```
{% endtab %}

{% tab v3_post_fast_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_fast_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_fast_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_fast_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_fast_example %}

{% tab v3_post_fast_example 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}'
```
{% endtab %}

{% tab v3_post_fast_example 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
```
{% endtab %}

{% tab v3_post_fast_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/imagine
parent: Midjourney API v3
nav_order: 600
---
## Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_imagine_json_response %}

{% tab v3_post_imagine_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab v3_post_imagine_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_imagine_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_imagine_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_imagine_json_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

Channel at capacity or rate limited. Wait 10-30 seconds and retry.

```json
{
  "error": "Channel 1234567890123456789 is busy executing 3 image jobs"
}
```

{% endtab %}

{% tab v3_post_imagine_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_imagine_example %}

{% tab v3_post_imagine_example 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}'
```
{% endtab %}

{% tab v3_post_imagine_example 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
```
{% endtab %}

{% tab v3_post_imagine_example 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
```
{% endtab %}

{% endtabs %}

### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/info
parent: Midjourney API v3
nav_order: 1100
---
## Get Midjourney Account Info
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_info_json_response %}

{% tab v3_post_info_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab v3_post_info_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "channel parameter is required when multiple channels (3) are configured"
}
```
{% endtab %}

{% tab v3_post_info_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_info_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_info_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_info_example %}

{% tab v3_post_info_example 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}'
```
{% endtab %}

{% tab v3_post_info_example 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
```
{% endtab %}

{% tab v3_post_info_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/relax
parent: Midjourney API v3
nav_order: 1300
---
## Switch to Relax Mode
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Switch Midjourney account to [Relax mode](https://docs.midjourney.com/docs/relax-mode) using the /relax command.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_relax_json_response %}

{% tab v3_post_relax_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```
{% endtab %}

{% tab v3_post_relax_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_relax_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_relax_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_relax_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_relax_example %}

{% tab v3_post_relax_example 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}'
```
{% endtab %}

{% tab v3_post_relax_example 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
```
{% endtab %}

{% tab v3_post_relax_example 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
```
{% endtab %}

{% endtabs %}

### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/remix
parent: Midjourney API v3
nav_order: 1600
---
## Toggle Remix Mode
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_remix_json_response %}

{% tab v3_post_remix_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab v3_post_remix_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_remix_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_remix_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_remix_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_remix_example %}

{% tab v3_post_remix_example 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}'
```
{% endtab %}

{% tab v3_post_remix_example 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
```
{% endtab %}

{% tab v3_post_remix_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/seed
parent: Midjourney API v3
nav_order: 1000
---
## Get Midjourney Seed
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve the [seed](https://docs.midjourney.com/docs/seeds) and **four separate upscaled** images for the following completed jobs: 
* [jobs/imagine](post-midjourney-jobs-imagine)
* [jobs/button](post-midjourney-jobs-button)
* [jobs/blend](post-midjourney-jobs-blend)

Please note that video generation jobs are not supported.

{: .post }
> **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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_seed_json_response %}

{% tab v3_post_seed_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab v3_post_seed_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Parent job status is \"progress\", must be \"completed\" to get seed"
}
```
{% endtab %}

{% tab v3_post_seed_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_seed_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_seed_json_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

```json
{
  "error": "Parent job not found"
}
```
{% endtab %}

{% tab v3_post_seed_json_response <span class="http-status-bad">410</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

Parent job expired (older than 62 days).

```json
{
  "error": "Parent job has expired"
}
```
{% endtab %}

{% tab v3_post_seed_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_seed_example %}

{% tab v3_post_seed_example 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}'
```
{% endtab %}

{% tab v3_post_seed_example 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
  })
});
```
{% endtab %}

{% tab v3_post_seed_example 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
    }
)
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/settings
parent: Midjourney API v3
nav_order: 1090
---
## Midjourney Settings
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.

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

{% tabs v3_post_settings_json_response %}

{% tab v3_post_settings_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab v3_post_settings_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "channel parameter is required when multiple channels (3) are configured"
}
```
{% endtab %}

{% tab v3_post_settings_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_settings_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_settings_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_settings_example %}

{% tab v3_post_settings_example 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}'
```
{% endtab %}

{% tab v3_post_settings_example 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
```
{% endtab %}

{% tab v3_post_settings_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/turbo
parent: Midjourney API v3
nav_order: 1400
---
## Switch to Turbo Mode
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Switch Midjourney account to Turbo mode using the /turbo command.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_turbo_json_response %}

{% tab v3_post_turbo_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```
{% endtab %}

{% tab v3_post_turbo_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_turbo_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_turbo_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_turbo_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_turbo_example %}

{% tab v3_post_turbo_example 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}'
```
{% endtab %}

{% tab v3_post_turbo_example 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
```
{% endtab %}

{% tab v3_post_turbo_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/variability
parent: Midjourney API v3
nav_order: 1500
---
## Toggle Variability Mode
{: .no_toc }

<small>October 27, 2025 (January 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Toggle Midjourney [Variability mode](https://docs.midjourney.com/docs/variations) using the /settings command.

{: .post }
> **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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide)
  - `false` - Returns `Content-Type: application/json` with initial job state. Use [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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.  

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

{% tabs v3_post_variability_json_response %}

{% tab v3_post_variability_json_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created successfully.
Use returned `jobid` with [GET /jobs/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab v3_post_variability_json_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Validation error.

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

{% endtab %}

{% tab v3_post_variability_json_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab v3_post_variability_json_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab v3_post_variability_json_response <span class="http-status-bad">596</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/596" rel="noreferrer" target="_blank"><span class="http-status-bad">596 Pending Moderation</span></a>

Channel has pending moderation/CAPTCHA. Email notification sent. Log into Discord and address moderation message/CAPTCHA. Execute [POST /accounts/<code class="language-plaintext highlighter-rouge">channel</code>/reset](https://useapi.net/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."
}
```

{% endtab %}

{% endtabs %}

### Response • SSE Stream • `stream: true`

Returns `content-type: text/event-stream` with real-time job progress events.
See [SSE Streaming Guide](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide) for implementation details.
See [Job Response Model](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/sse-streaming-guide).

{% tabs v3_post_variability_example %}

{% tab v3_post_variability_example 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}'
```
{% endtab %}

{% tab v3_post_variability_example 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
```
{% endtab %}

{% tab v3_post_variability_example 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
```
{% endtab %}

{% endtabs %}


### Try It

<script src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: 🚀 Quick Start
parent: Midjourney API v3
nav_order: 160
---
## Quick Start
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

## Prerequisites

Before you begin, make sure you have:

* Active subscription - [Subscribe](../../docs/start-here/setup-useapi#subscription)
* 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](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts) for full documentation.

## Generate with Real-time SSE

See [SSE Streaming Guide](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts)
3. Update your code to use [v3 endpoints](.)
4. Enable `stream: true` for real-time updates (recommended)

See account management endpoints:
- [POST /accounts](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts) - Configure channel
- [GET /accounts](https://useapi.net/docs/api-midjourney-v3/get-midjourney-accounts) - List channels
- [DELETE /accounts/<code class="language-plaintext highlighter-rouge">channel</code>](https://useapi.net/docs/api-midjourney-v3/delete-midjourney-accounts-channel) - Remove channel
  
## Next Steps

- Explore [What's New in v3](https://useapi.net/docs/api-midjourney-v3/what-new) features
- Check [SSE Streaming Guide](https://useapi.net/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
---
layout: default
title: ⚙️ Setup multiple accounts
parent: Midjourney API v3
nav_order: 4000
---
## How to use multiple Midjourney accounts
{: .no_toc }

<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](https://useapi.net/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](../start-here/setup-midjourney).
- Post your configuration(s) using the [POST /accounts](https://useapi.net/docs/api-midjourney-v3/post-midjourney-accounts) endpoint.

To see all your currently configured Midjourney accounts, please use the [GET /accounts](https://useapi.net/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](../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
---
layout: default
title: ⚡SSE Streaming Guide
parent: Midjourney API v3
nav_order: 170
---
## Real-Time SSE Streaming Guide
{: .no_toc }

<small>October 27, 2025 (November 26, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](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](https://useapi.net/docs/api-midjourney-v3/get-midjourney-jobs-jobid#model) for complete response structure.

### Examples

{% tabs sse_example %}

{% tab sse_example 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.
{% endtab %}

{% tab sse_example 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');
```
{% endtab %}

{% tab sse_example 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')
```
{% endtab %}

{% endtabs %}

## 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/<code class="language-plaintext highlighter-rouge">jobid</code>) 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](https://useapi.net/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
---
layout: default
title: 🖌️ Vary Region mask editor
parent: Midjourney API v3
nav_order: 3000
---
## Simple Vary Region (inpaint) mask editor
{: .no_toc }

<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](https://useapi.net/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
---
layout: default
title: 🆕 What's New in v3
parent: Midjourney API v3
nav_order: 150
---
## What's New in v3
{: .no_toc }

<small>October 27, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

### 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](https://useapi.net/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](https://useapi.net/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](https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-info) - Account info with speed mode settings
- [POST /jobs/fast](https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-fast), [/relax](https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-relax), [/turbo](https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-turbo) - Toggle speed modes
- [POST /jobs/remix](https://useapi.net/docs/api-midjourney-v3/post-midjourney-jobs-remix), [/variability](https://useapi.net/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/<code class="language-plaintext highlighter-rouge">jobid</code>](https://useapi.net/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
---
layout: default
title: Setup MiniMax
parent: Start Here
nav_order: 350
---
# <img style="height:1.5em;vertical-align: middle;" src="https://useapi.net/assets/images/minimax.png"> Setup MiniMax | Hailuo AI
{: .no_toc }

<small>September 25, 2024 (November 24, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 5 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [MiniMax API](../api-minimax-v1). A [Hailuo AI](https://hailuoai.video) account and a [useapi.net subscription](../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](../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="https://useapi.net/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
---
layout: default
title: MiniMax API v1
nav_order: 3000
has_children: true
permalink: /docs/api-minimax-v1
---

# <img style="height:1.5em;vertical-align: middle;" src="https://useapi.net/assets/images/minimax.png"> MiniMax API v1

<small>September 25, 2024 (February 27, 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 15 models across 3 families: [Hailuo 01/02/2.3](https://hailuoai.video), [Veo 3.1](https://deepmind.google/models/veo/) (including S2V subject reference), and [Sora 2](https://openai.com/sora/). These models are notable for generating ultra-realistic video clips with precise prompt following.
* MiniMax [images](api-minimax-v1/post-minimax-images-create) supports 8 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/), [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 |

**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 |

**Audio** — 1 credit per song

</details>

[Setup MiniMax](../../docs/start-here/setup-minimax)

[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-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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: MiniMax API v1
nav_order: 400
---
## Delete MiniMax API account
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](post-minimax-accounts-account) request.

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

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

##### Responses 

{% tabs del_account_MiniMax_response %}

{% tab del_account_MiniMax_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_MiniMax_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_MiniMax_example %}

{% tab del_account_MiniMax_example 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> 
```
{% endtab %}

{% tab del_account_MiniMax_example 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});
```
{% endtab %}

{% tab del_account_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> audio/<code class="language-plaintext highlighter-rouge">audio_id</code>
nav_order: 2800
nav_exclude: true
---
## Delete text-to-speech audio clip 
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../start-here/setup-minimax) for details.

This endpoint will delete audio clip generated by 

* [POST audio/create-mp3](https://useapi.net/docs/api-minimax-v1/post-minimax-audio-create-mp3)
* [POST audio/create-stream](https://useapi.net/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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify the audio_id you want to delete.   

##### Responses 

{% tabs del_MiniMax_audio_audio_id_response %}

{% tab del_MiniMax_audio_audio_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_MiniMax_audio_audio_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_MiniMax_audio_audio_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_MiniMax_audio_audio_id_example %}

{% tab del_MiniMax_audio_audio_id_example Curl %}
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/audio/<audio_id>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_MiniMax_audio_audio_id_example 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});
```
{% endtab %}

{% tab del_MiniMax_audio_audio_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files/<code class="language-plaintext highlighter-rouge">fileID</code>
parent: MiniMax API v1
nav_order: 3500
---
## Delete file
{: .no_toc }

<small>December 23, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to delete file uploaded by

* [POST files](https://useapi.net/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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `fileID` is **required**. Specify the fileID you want to delete.   

##### Responses 

{% tabs del_MiniMax_files_fileID_response %}

{% tab del_MiniMax_files_fileID_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_MiniMax_files_fileID_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_MiniMax_files_fileID_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_MiniMax_files_fileID_example %}

{% tab del_MiniMax_files_fileID_example Curl %}
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/files/fileID" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_MiniMax_files_fileID_example 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});
```
{% endtab %}

{% tab del_MiniMax_files_fileID_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> images/<code class="language-plaintext highlighter-rouge">imageId</code>
parent: MiniMax API v1
nav_order: 1400
---
## Delete image 
{: .no_toc }

<small>March 17, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to delete image generated by

* [POST images/create](https://useapi.net/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](https://useapi.net/docs/api-minimax-v1/get-minimax-images), you can still retrieve it via [GET images/`imageId`](https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId).

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to delete.   

##### Responses 

{% tabs del_MiniMax_images_imageId_response %}

{% tab del_MiniMax_images_imageId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_MiniMax_images_imageId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_MiniMax_images_imageId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_MiniMax_images_imageId_example %}

{% tab del_MiniMax_images_imageId_example Curl %}
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/images/<imageId>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_MiniMax_images_imageId_example 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});
```
{% endtab %}

{% tab del_MiniMax_images_imageId_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-llm
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> llm
nav_order: 1800
nav_exclude: true
---
## Delete LLM chats and/or messages
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../start-here/setup-minimax) for details.

{: .delete }
> **https://api.useapi.net/v1/minimax/llm/?…**

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

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

##### Query Parameters

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](../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 

{% tabs get_llm_MiniMax_llm_response %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs get_llm_MiniMax_llm_example %}

{% tab get_llm_MiniMax_llm_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/llm/?account=<account>&msgID=<msgID>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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});
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/<code class="language-plaintext highlighter-rouge">id</code>
parent: MiniMax API v1
nav_order: 3800
---
## Remove video or image generation from being tracked by the scheduler
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **https://api.useapi.net/v1/minimax/scheduler/`id`**

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

##### Path parameter
- `id` is **required**. Specify videoId or imageId you want to stop tracking.

##### Responses 

{% tabs delete_scheduler_MiniMax_scheduler_response %}

{% tab delete_scheduler_MiniMax_scheduler_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>  
{% endtab %}

{% tab delete_scheduler_MiniMax_scheduler_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab delete_scheduler_MiniMax_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_scheduler_MiniMax_scheduler_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
  "error": "Unable to locate running <id>"
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs delete_scheduler_MiniMax_scheduler_example %}

{% tab delete_scheduler_MiniMax_scheduler_example 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>" 
```
{% endtab %}

{% tab delete_scheduler_MiniMax_scheduler_example 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});
```
{% endtab %}

{% tab delete_scheduler_MiniMax_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> videos/<code class="language-plaintext highlighter-rouge">videoId</code>
parent: MiniMax API v1
nav_order: 1000
---
## Delete video 
{: .no_toc }

<small>December 23, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to delete video generated by

* [videos/create](https://useapi.net/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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to delete.   

##### Responses 

{% tabs del_MiniMax_videos_videoId_response %}

{% tab del_MiniMax_videos_videoId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_MiniMax_videos_videoId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_MiniMax_videos_videoId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_MiniMax_videos_videoId_example %}

{% tab del_MiniMax_videos_videoId_example Curl %}
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/videos/videoId" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_MiniMax_videos_videoId_example 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});
```
{% endtab %}

{% tab del_MiniMax_videos_videoId_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: MiniMax API v1
nav_order: 200
---
## Retrieve MiniMax API account configuration for `account` 
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](post-minimax-accounts-account) request.

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

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

##### Responses 

{% tabs get_account_MiniMax_account_response %}

{% tab get_account_MiniMax_account_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
}
```
{% endtab %}

{% tab get_account_MiniMax_account_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_MiniMax_account_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

Configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account).

{% endtab %}

{% endtabs %}

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

{% tabs get_account_MiniMax_account_example %}

{% tab get_account_MiniMax_account_example Curl %}
``` bash
curl https://api.useapi.net/v1/minimax/accounts/<account> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_MiniMax_account_example 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});
```
{% endtab %}

{% tab get_account_MiniMax_account_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: MiniMax API v1
nav_order: 100
---
## Retrieve MiniMax API accounts configuration
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_MiniMax_response %}

{% tab account_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
    }
}
```
{% endtab %}

{% tab account_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_MiniMax_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account).

{% endtab %}

{% endtabs %}

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

{% tabs account_MiniMax_example %}

{% tab account_MiniMax_example Curl %}
``` bash
curl https://api.useapi.net/v1/minimax/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_MiniMax_example 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});
```
{% endtab %}

{% tab account_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/<code class="language-plaintext highlighter-rouge">jobId</code>
parent: MiniMax API v1
nav_order: 2100
---
## Retrieve Agent Job Status and Results
{: .no_toc }

<small>November 24, 2025 (November 26, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-minimax-v1/post-minimax-agent) using `async: true`.

{: .get }
> **https://api.useapi.net/v1/minimax/agent/`jobId`**

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

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

##### Path Parameters

- `jobId` is **required**. The job ID to query.

##### Responses

{% tabs get_agent_jobid_response %}

{% tab get_agent_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
    }
}
```

{% endtab %}

{% tab get_agent_jobid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid job ID format or access denied.

```json
{
  "error": "Error …",
  "code": 400
}
```
{% endtab %}

{% tab get_agent_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab get_agent_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found or expired after 31 days.

```json
{
  "error": "Job not found or expired after 31 days",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_agent_jobid_example %}

{% tab get_agent_jobid_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/p123456789-u12345-a67890-bot:minimax"
```
{% endtab %}

{% tab get_agent_jobid_example 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);
}
```
{% endtab %}

{% tab get_agent_jobid_example 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']}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/jobs
parent: MiniMax API v1
nav_order: 2200
---
## List Running Agent Jobs
{: .no_toc }

<small>November 24, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId) if you have the job ID.

{: .get }
> **https://api.useapi.net/v1/minimax/agent/jobs**

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

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

##### Responses

{% tabs get_agent_jobs_response %}

{% tab get_agent_jobs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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"
            }
        ]
    }
}
```

{% endtab %}

{% tab get_agent_jobs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs get_agent_jobs_example %}

{% tab get_agent_jobs_example Curl %}
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/jobs"
```
{% endtab %}

{% tab get_agent_jobs_example 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})`);
  });
}
```
{% endtab %}

{% tab get_agent_jobs_example 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']})")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> audio/config
nav_order: 2700
nav_exclude: true
---
## Retrieve audio configuration parameters
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../start-here/setup-minimax) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs   get_MiniMax_audio_config_response %}

{% tab   get_MiniMax_audio_config_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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": "..."
        }
    ]
}
```
{% endtab %}

{% tab   get_MiniMax_audio_config_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab   get_MiniMax_audio_config_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs   get_MiniMax_audio_config_example %}

{% tab   get_MiniMax_audio_config_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/audio/config/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab   get_MiniMax_audio_config_example 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});
```
{% endtab %}

{% tab   get_MiniMax_audio_config_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> audio/voices
nav_order: 2600
nav_exclude: true
---
## Retrieve the list of system and cloned audio voices
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../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
  
{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../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](../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 

{% tabs get_MiniMax_audio_voices_response %}

{% tab get_MiniMax_audio_voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

`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
}
```
{% endtab %}

{% tab get_MiniMax_audio_voices_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_MiniMax_audio_voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_MiniMax_audio_voices_example %}

{% tab get_MiniMax_audio_voices_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/audio/voices/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_MiniMax_audio_voices_example 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});
```
{% endtab %}

{% tab get_MiniMax_audio_voices_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-audio
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> audio
nav_order: 2400
nav_exclude: true
---
## Retrieve the list of text-to-speech audio clips you have generated
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../start-here/setup-minimax) for details.

This endpoint will return audio clips generated by 

* [POST audio/create-mp3](https://useapi.net/docs/api-minimax-v1/get-minimax-audio-create-mp3)
* [POST audio/create-stream](https://useapi.net/docs/api-minimax-v1/get-minimax-audio-create-stream)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_MiniMax_audio_response %}

{% tab get_MiniMax_audio_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_MiniMax_audio_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_MiniMax_audio_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_MiniMax_audio_example %}

{% tab get_MiniMax_audio_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/audio/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_MiniMax_audio_example 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});
```
{% endtab %}

{% tab get_MiniMax_audio_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> audio/<code class="language-plaintext highlighter-rouge">audio_id</code>
nav_order: 2500
nav_exclude: true
---
## Retrieve text-to-speech audio clip
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../start-here/setup-minimax) for details.

This endpoint will return audio clip generated by 

* [POST audio/create-mp3](https://useapi.net/docs/api-minimax-v1/get-minimax-audio-create-mp3)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify audio clip you want to retrieve.

##### Responses 

{% tabs get_MiniMax_audio_audio_id_response %}

{% tab get_MiniMax_audio_audio_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
    }
}
```
{% endtab %}

{% tab get_MiniMax_audio_audio_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_MiniMax_audio_audio_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_MiniMax_audio_audio_id_example %}

{% tab get_MiniMax_audio_audio_id_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/audio/audio_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_MiniMax_audio_audio_id_example 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});
```
{% endtab %}

{% tab get_MiniMax_audio_audio_id_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features
parent: MiniMax API v1
nav_order: 450
---
## Retrieve your hailuoai.video and minimax.io/audio accounts information
{: .no_toc }

<small>October 14, 2024 (May 31, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve your [hailuoai.video](https://hailuoai.video) and [www.minimax.io/audio](https://www.minimax.io/audio) accounts information, see [Setup MiniMax](../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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_features_MiniMax_features_response %}

{% tab get_features_MiniMax_features_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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": {}
    }
}
```
{% endtab %}

{% tab get_features_MiniMax_features_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_features_MiniMax_features_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_features_MiniMax_features_example %}

{% tab get_features_MiniMax_features_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/features/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_features_MiniMax_features_example 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});
```
{% endtab %}

{% tab get_features_MiniMax_features_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files
parent: MiniMax API v1
nav_order: 3400
---
## Retrieve the list of images you have uploaded
{: .no_toc }

<small>October 14, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of uploaded images, see [Setup MiniMax](../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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_files_MiniMax_files_response %}

{% tab get_files_MiniMax_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
    }
]
```
{% endtab %}

{% tab get_files_MiniMax_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_files_MiniMax_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_files_MiniMax_files_example %}

{% tab get_files_MiniMax_files_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/files/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_files_MiniMax_files_example 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});
```
{% endtab %}

{% tab get_files_MiniMax_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/<code class="language-plaintext highlighter-rouge">imageId</code>
parent: MiniMax API v1
nav_order: 1300
---
## Retrieve image 
{: .no_toc }

<small>March 17, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of

* [POST images/create](https://useapi.net/docs/api-minimax-v1/post-minimax-images-create)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to retrieve.   

##### Responses 

{% tabs get_images_imageId_MiniMax_images_imageId_response %}

{% tab get_images_imageId_MiniMax_images_imageId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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>"
}
```
{% endtab %}

{% tab get_images_imageId_MiniMax_images_imageId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_images_imageId_MiniMax_images_imageId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_images_imageId_MiniMax_images_imageId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_images_imageId_MiniMax_images_imageId_example %}

{% tab get_images_imageId_MiniMax_images_imageId_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/images/<imageId>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_images_imageId_MiniMax_images_imageId_example 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});
```
{% endtab %}

{% tab get_images_imageId_MiniMax_images_imageId_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images
parent: MiniMax API v1
nav_order: 1200
---
## Retrieve the list of images you have generated
{: .no_toc }

<small>March 17, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](../start-here/setup-minimax) for details.

Returned image `fileID` value can be used as a parameter for [POST videos/create](../api-minimax-v1/post-minimax-videos-create).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_images_MiniMax_images_response %}

{% tab get_images_MiniMax_images_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_images_MiniMax_images_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_images_MiniMax_images_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_images_MiniMax_images_example %}

{% tab get_images_MiniMax_images_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/images/?account=<account>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_images_MiniMax_images_example 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});
```
{% endtab %}

{% tab get_images_MiniMax_images_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> llm/<code class="language-plaintext highlighter-rouge">chatID</code>
nav_order: 1700
nav_exclude: true
---
## Retrieve the messages from the LLM chat
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../start-here/setup-minimax) for details.

{: .get }
> **https://api.useapi.net/v1/minimax/llm/`chatID`/?…**

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

- `API token` is **required**, see [Setup useapi.net](../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](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_llm_MiniMax_llm_response %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
}
```

{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_llm_MiniMax_llm_example %}

{% tab get_llm_MiniMax_llm_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/llm/<chatID>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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});
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-llm
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> llm
nav_order: 1600
nav_exclude: true
---
## Retrieve the list of LLM chats
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../start-here/setup-minimax) for details.

{: .get }
> **https://api.useapi.net/v1/minimax/llm/?…**

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

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

##### Query Parameters

- `account` is optional when only one LLM [chat.minimax.io](https://chat.minimax.io) [account](../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 

{% tabs get_llm_MiniMax_llm_response %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
        }
    ]
}
```
{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_llm_MiniMax_llm_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_llm_MiniMax_llm_example %}

{% tab get_llm_MiniMax_llm_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/llm/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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});
```
{% endtab %}

{% tab get_llm_MiniMax_llm_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/create
nav_order: 2900
nav_exclude: true
---
## Compose music up to 60 seconds long using a text prompt
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../start-here/setup-minimax) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../api-minimax-v1/get-minimax-music-styles).
  
- `title` is optional. 

##### Responses 

{% tabs post_music-create_MiniMax_response %}

{% tab post_music-create_MiniMax_response <span class="http-status-good">200</span> %}

Use the returned `musicId` to retrieve full music results, such as `coverURL`, `style`, `lyrics` and moderation `status` by using [GET /music/`musicId`](../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](../api-minimax-v1/get-minimax-music) and can only be retrieved by the [GET /music/`musicId`](../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,
}
```

{% endtab %}

{% tab post_music-create_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_music-create_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_music-create_MiniMax_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated prompt.

```json
{
    "error": "Moderated prompt"
}
```

{% endtab %}

{% tab post_music-create_MiniMax_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

Only one concurrent music generation is supported per account.

```json
{
    "error": "The previous request has not been completed yet. Please try again later."
}
```

{% endtab %}


{% endtabs %}

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

##### Examples

{% tabs post_music-create_MiniMax_example %}

{% tab post_music-create_MiniMax_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/music/create?styleId=…&prompt=…" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab post_music-create_MiniMax_example 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});
```
{% endtab %}

{% tab post_music-create_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/<code class="language-plaintext highlighter-rouge">musicId</code>
nav_order: 3000
nav_exclude: true
---
## Retrieve music 
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of

* [music/create](https://useapi.net/docs/api-minimax-v1/get-minimax-music-create)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `musicId` is **required**. Specify the musicId you want to retrieve.   

##### Responses 

{% tabs get_music_musicId_MiniMax_music_musicId_response %}

{% tab get_music_musicId_MiniMax_music_musicId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
}
```
{% endtab %}

{% tab get_music_musicId_MiniMax_music_musicId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_musicId_MiniMax_music_musicId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_musicId_MiniMax_music_musicId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_music_musicId_MiniMax_music_musicId_example %}

{% tab get_music_musicId_MiniMax_music_musicId_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/music/musicId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_musicId_MiniMax_music_musicId_example 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});
```
{% endtab %}

{% tab get_music_musicId_MiniMax_music_musicId_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/styles
nav_order: 3100
nav_exclude: true
---
## Retrieve the list of music styles
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

You can preview all styles at [music/create](../api-minimax-v1/get-minimax-music-create#try-it)

Use [hailuoai.com/music](https://hailuoai.com/music) account to generate music, see [Setup MiniMax](../start-here/setup-minimax) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `account` is optional when only one [account](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_music_styles_MiniMax_music_styles_response %}

{% tab get_music_styles_MiniMax_music_styles_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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>"
            }
        ]
    }    
]
```
{% endtab %}

{% tab get_music_styles_MiniMax_music_styles_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_styles_MiniMax_music_styles_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    name: string
    styles: {
        url: string
        styleId: string
        name: string
    }[]
}[]
```

##### Examples

{% tabs get_music_styles_MiniMax_music_styles_example %}

{% tab get_music_styles_MiniMax_music_styles_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/music/styles/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_styles_MiniMax_music_styles_example 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});
```
{% endtab %}

{% tab get_music_styles_MiniMax_music_styles_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music
nav_order: 3200
nav_exclude: true
---
## Retrieve the list of songs you have generated
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.com/music](https://hailuoai.com/music) account to retrieve generated music, see [Setup MiniMax](../start-here/setup-minimax) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_music_MiniMax_music_response %}

{% tab get_music_MiniMax_music_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
    },
]
```
{% endtab %}

{% tab get_music_MiniMax_music_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_MiniMax_music_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_music_MiniMax_music_example %}

{% tab get_music_MiniMax_music_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/music/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_MiniMax_music_example 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});
```
{% endtab %}

{% tab get_music_MiniMax_music_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available
parent: MiniMax API v1
nav_order: 3700
---
## Retrieve the list of videos currently running via the API along with the available account capacity
{: .no_toc }

<small>October 15, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../api-minimax-v1/get-minimax-images). 

Please refer to code provided in article [Fun with MiniMax API](../articles/minimax-bash) to see how this endpoint can be used in conjunction with [POST /files](https://useapi.net/docs/api-minimax-v1/post-minimax-files) and [POST videos/create](https://useapi.net/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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs get_scheduler_available_MiniMax_scheduler_available_response %}

{% tab get_scheduler_available_MiniMax_scheduler_available_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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
        }
    ]
}
```
{% endtab %}

{% tab get_scheduler_available_MiniMax_scheduler_available_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_scheduler_available_MiniMax_scheduler_available_example %}

{% tab get_scheduler_available_MiniMax_scheduler_available_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_scheduler_available_MiniMax_scheduler_available_example 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});
```
{% endtab %}

{% tab get_scheduler_available_MiniMax_scheduler_available_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: MiniMax API v1
nav_order: 3600
---
## Retrieve the list of images and videos currently being executed by the API
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../api-minimax-v1/get-minimax-images). 

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs get_scheduler_MiniMax_scheduler_response %}

{% tab get_scheduler_MiniMax_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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>"
    }
]
```
{% endtab %}

{% tab get_scheduler_MiniMax_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
    videoId: string
    imageId: string
    started: number
    elapsed: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

{% tabs get_scheduler_MiniMax_scheduler_example %}

{% tab get_scheduler_MiniMax_scheduler_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_scheduler_MiniMax_scheduler_example 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});
```
{% endtab %}

{% tab get_scheduler_MiniMax_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/agent-templates
parent: MiniMax API v1
nav_order: 701
---
## Retrieve available agent video templates
{: .no_toc }

<small>June 30, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve available agent video templates, see [Setup MiniMax](../start-here/setup-minimax) for details.

Templates can be used with [POST videos/agent-create](../api-minimax-v1/post-minimax-videos-agent-create) to generate videos.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_videos_agent_templates_MiniMax_response %}

{% tab get_videos_agent_templates_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

**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",
        }
    ]
}
```
{% endtab %}

{% tab get_videos_agent_templates_MiniMax_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_videos_agent_templates_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_videos_agent_templates_MiniMax_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_videos_agent_templates_MiniMax_example %}

{% tab get_videos_agent_templates_MiniMax_example 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 …" 
```
{% endtab %}

{% tab get_videos_agent_templates_MiniMax_example 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});
```
{% endtab %}

{% tab get_videos_agent_templates_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/characters
parent: MiniMax API v1
nav_order: 800
---
## Retrieve the list of characters
{: .no_toc }

<small>January 9, 2025 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](../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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_MiniMax_videos_characters_response %}

{% tab get_MiniMax_videos_characters_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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/..."
        }
    }
]
```
{% endtab %}

{% tab get_MiniMax_videos_characters_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_MiniMax_videos_characters_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    characterID: string
    characterType: number
    file: {
        fileID: string
        cdnUrl: string
        promptImgUrl: string
    }
}[]
```

##### Examples

{% tabs get_MiniMax_videos_characters_example %}

{% tab get_MiniMax_videos_characters_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/videos/characters/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_MiniMax_videos_characters_example 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});
```
{% endtab %}

{% tab get_MiniMax_videos_characters_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/<code class="language-plaintext highlighter-rouge">videoId</code>
parent: MiniMax API v1
nav_order: 600
---
## Retrieve video 
{: .no_toc }

<small>September 25, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of

* [videos/create](https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to retrieve.   

##### Responses 

{% tabs get_videos_videoId_MiniMax_videos_videoId_response %}

{% tab get_videos_videoId_MiniMax_videos_videoId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
}
```
{% endtab %}

{% tab get_videos_videoId_MiniMax_videos_videoId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_videos_videoId_MiniMax_videos_videoId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_videos_videoId_MiniMax_videos_videoId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

This most often means that the video was moderated and removed after it was generated.

```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_videos_videoId_MiniMax_videos_videoId_example %}

{% tab get_videos_videoId_MiniMax_videos_videoId_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/videos/videoId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_videos_videoId_MiniMax_videos_videoId_example 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});
```
{% endtab %}

{% tab get_videos_videoId_MiniMax_videos_videoId_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos
parent: MiniMax API v1
nav_order: 700
---
## Retrieve the list of videos you have generated
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](../start-here/setup-minimax) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_videos_MiniMax_videos_response %}

{% tab get_videos_MiniMax_videos_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
    }
]
```
{% endtab %}

{% tab get_videos_MiniMax_videos_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_videos_MiniMax_videos_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_videos_MiniMax_videos_example %}

{% tab get_videos_MiniMax_videos_example Curl %}
``` bash
curl "https://api.useapi.net/v1/minimax/videos/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_videos_MiniMax_videos_example 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});
```
{% endtab %}

{% tab get_videos_MiniMax_videos_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: MiniMax API v1
nav_order: 300
---
## Create or update MiniMax API account configuration
{: .no_toc }

<small>September 25, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

See [Setup MiniMax](../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.

{: .post }
> **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](../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](../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 

{% tabs post_account_MiniMax_response %}

{% tab post_account_MiniMax_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a> 

```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
}
```

{% endtab %}

{% tab post_account_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_account_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_account_MiniMax_example %}

{% tab post_account_MiniMax_example 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": …}'
```
{% endtab %}

{% tab post_account_MiniMax_example 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});
```
{% endtab %}

{% tab post_account_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent
parent: MiniMax API v1
nav_order: 2000
---
## Execute AI Agent with Multi-Model Support
{: .no_toc }

<small>November 24, 2025 (February 24, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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](../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.

{: .post }
> **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](../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](../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](https://useapi.net/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

{% tabs post_agent_minimax_response %}

{% tab post_agent_minimax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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"
                    }
                }
            }
        ]
    }
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Agent task created and processing in background (asynchronous mode with `async: true`).

Use the returned `jobId` to check status via [GET agent/`jobId`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid request parameters.

```json
{
  "error": "Error …",
  "code": 400
}
```
{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated content or invalid file.

```json
{
  "error": "Your prompt contains content that violates our policies"
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

Dynamic capacity limit reached. Wait for at least one job to complete (or wait ~30 seconds) and try again.

```json
{
  "error": "Agent generation failed"
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">500</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500" rel="noreferrer" target="_blank"><span class="http-status-bad">500 Internal Server Error</span></a>

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
  }
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">504</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504" rel="noreferrer" target="_blank"><span class="http-status-bad">504 Gateway Timeout</span></a>

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
  }
}
```

{% endtab %}

{% tab post_agent_minimax_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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"
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_agent_minimax_example %}

{% tab post_agent_minimax_example 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"
```
{% endtab %}

{% tab post_agent_minimax_example 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);
```
{% endtab %}

{% tab post_agent_minimax_example 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'])
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> audio/clone-voice
nav_order: 2200
nav_exclude: true
---
## Clone a voice using uploaded audio samples
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../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.

{: .post }
> **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](../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](../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](../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 

{% tabs post-MiniMax_audio-clone-voice_response %}

{% tab post-MiniMax_audio-clone-voice_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```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>"
}
```

{% endtab %}

{% tab post-MiniMax_audio-clone-voice_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "<Error message>"
}
```

{% endtab %}

{% tab post-MiniMax_audio-clone-voice_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% endtabs %}

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

{% tabs post_MiniMax_audio_clone_voice_example %}

{% tab post_MiniMax_audio_clone_voice_example 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": …}'
```
{% endtab %}

{% tab post_MiniMax_audio_clone_voice_example 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});
```
{% endtab %}

{% tab post_MiniMax_audio_clone_voice_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> audio/create-mp3
nav_order: 1900
nav_exclude: true
---
## Create text-to-speech audio 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../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](../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

{: .post }
> **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](../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](../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](../api-minimax-v1/post-minimax-audio-create-stram) and [WSS audio/wss](../api-minimax-v1/wss-minimax-audio-wss).  

- `voice_id` is **required**. Use [GET audio/voices](../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](../api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `emotion` is optional. Use value from array `t2a_emotion` of [GET audio/config](../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 

{% tabs post-MiniMax_audio-create-mp3_response %}

{% tab post-MiniMax_audio-create-mp3_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `audio_url` to download generated mp3 audio file.   
Use returned `audio_id` to retrieve full details using [GET audio/`audio_id`](../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
}
```

{% endtab %}

{% tab post-MiniMax_audio-create-mp3_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post-MiniMax_audio-create-mp3_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post-MiniMax_audio-create-mp3_example %}

{% tab post-MiniMax_audio-create-mp3_example 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": "…"}'
```
{% endtab %}

{% tab post-MiniMax_audio-create-mp3_example 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});
```
{% endtab %}

{% tab post-MiniMax_audio-create-mp3_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> audio/create-stream
nav_order: 2000
nav_exclude: true
---
## Create text-to-speech audio stream token and payload
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../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](../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](../api-minimax-v1/wss-minimax-audio-wss).

{: .post }
> **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](../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](../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](../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](../api-minimax-v1/get-minimax-audio-config).  
  Default value `Auto`.

- `emotion` is optional. Use value from array `t2a_emotion` of [GET audio/config](../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 

{% tabs post-MiniMax_audio-create-stream_response %}

{% tab post-MiniMax_audio-create-stream_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Field `token` and `payload` values are used by WebSocket [WSS audio/wss](../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
        }
    }
}
```

{% endtab %}

{% tab post-MiniMax_audio-create-stream_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "<Error message>"
}
```

{% endtab %}

{% tab post-MiniMax_audio-create-stream_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% endtabs %}

##### Examples

The code provided at [WSS audio/wss](../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](../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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> audio/delete-voice
nav_order: 2300
nav_exclude: true
---
## Delete cloned voice

{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../start-here/setup-minimax) for details.

This endpoint deletes a voice cloned via [POST audio/clone-voice](../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.

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax account",
    "voice_id": "1234567890",
}
```

- `account` is optional when only one [account](../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](../api-minimax-v1/post-minimax-audio-clone-voice) or [GET audio/voices/?is_system=false](../api-minimax-v1/get-minimax-audio-voices) 

##### Responses 

{% tabs post_MiniMax_audio_delete_voice_response %}

{% tab post_MiniMax_audio_delete_voice_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

{% endtab %}

{% tab post_MiniMax_audio_delete_voice_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_MiniMax_audio_delete_voice_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_MiniMax_audio_delete_voice_example %}

{% tab post_MiniMax_audio_delete_voice_example 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": "…"}'
```
{% endtab %}

{% tab post_MiniMax_audio_delete_voice_example 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});
```
{% endtab %}

{% tab post_MiniMax_audio_delete_voice_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> audio/upload-sample
nav_order: 2100
nav_exclude: true
---
## Upload audio samples for voice cloning  
{: .no_toc }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Please configure at least one [www.minimax.io/audio](https://www.minimax.io/audio) account for this endpoint, see [Setup MiniMax](../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](../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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs post_MiniMax_audio_upload_sample_response %}

{% tab post_MiniMax_audio_upload_sample_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```
{% endtab %}

{% tab post_MiniMax_audio_upload_sample_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_MiniMax_audio_upload_sample_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_MiniMax_audio_upload_sample_example %}

{% tab post_MiniMax_audio_upload_sample_example 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
```
{% endtab %}

{% tab post_MiniMax_audio_upload_sample_example 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});
```
{% endtab %}

{% tab post_MiniMax_audio_upload_sample_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files
parent: MiniMax API v1
nav_order: 3300
---
## Upload image 
{: .no_toc }

<small>October 15, 2024 (March 17, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to upload image, see [Setup MiniMax](../start-here/setup-minimax) for details.

Upload `.png` and `.jpeg` images up to 5GB in size that you want to use for your image generations via [POST videos/create](../api-minimax-v1/post-minimax-videos-create). You can also upload `.webp` files using `Content-Type: image/jpeg`.  

Please **be patient**, on average, it takes about 1 minute per GB to upload.

[POST raw content using Make.com and similar nocode tools.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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           |

##### Query Parameters

- `account` is optional when only one [account](../api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs post_files_MiniMax_files_response %}

{% tab post_files_MiniMax_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```
{% endtab %}

{% tab post_files_MiniMax_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_files_MiniMax_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_files_MiniMax_files_example %}

{% tab post_files_MiniMax_files_example 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
```
{% endtab %}

{% tab post_files_MiniMax_files_example 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});
```
{% endtab %}

{% tab post_files_MiniMax_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create
parent: MiniMax API v1
nav_order: 1100
---
## Create an image using a text prompt
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<small>March 17, 2025 (February 27, 2026)</small>

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](../start-here/setup-minimax) for details.

##### Model Comparison Matrix

| Model | Resolutions | Aspect Ratios | Ref Images |
|:------|:------------|:--------------|:-----------|
| 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` |
| 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, 4K | 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` |

<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 |
| seedream-4.5 | 2K, 4K | 4 | 1-4 |
| seedream-5.0 | 2K, 4K | 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`](https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId)
* [GET images](https://useapi.net/docs/api-minimax-v1/get-minimax-images)

{: .post }
> **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](../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](../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`, `seedream-4.5`; 5,000 characters for `nano-banana-2`, `nano-banana-pro`, `seedream-5.0`, `midjourney-v7`, `midjourney-niji7`.

- `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.
  * `seedream-4.5` - High-resolution image generation (2K/4K) with up to 14 reference images.
  * `seedream-5.0` - High-resolution image generation (2K/4K) 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`.
  * `seedream-4.5`: `2K` (default), `4K`.
  * `seedream-5.0`: `2K` (default), `4K`.
  * `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`.
  * `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`.

- `characterFileId` is optional, **only for `image-01`**:
    * fileID of the character image uploaded via [POST /files](../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`…`14` instead).

- `referenceFileId1` … `referenceFileId14` are optional, **for all models except `image-01`**:
    * fileID(s) of reference images uploaded via [POST /files](../api-minimax-v1/post-minimax-files).
    * `nano-banana-2`, `nano-banana-pro`, `seedream-4.5`, `seedream-5.0`, `midjourney-v7`, `midjourney-niji7`: Supports 1-14 reference images for style and content guidance.
    * `gpt-image-1.5`: Supports 1-3 reference images (`referenceFileId1`…`3` only).
    * All reference files must belong to the same account.
    * Cannot be used with `image-01` model (use `characterFileId` instead).

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

- `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 

{% tabs post_images-create_MiniMax_response %}

{% tab post_images-create_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned in array `imageIds` values to retrieve image status and results using [GET images/`imageId`](../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`](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
}
```

{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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"
}
```

{% endtab %}

{% tab post_images-create_MiniMax_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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"
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_images-create_MiniMax_example %}

{% tab post_images-create_MiniMax_example 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": "…"}'
```
{% endtab %}

{% tab post_images-create_MiniMax_example 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});
```
{% endtab %}

{% tab post_images-create_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-llm ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-llm
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> llm
nav_order: 1500
nav_exclude: true
---
## Chat with LLM

{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

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

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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 

{% tabs post_llm_MiniMax_response %}

{% tab post_llm_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

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
      }
    }
  }
  ```

{% endtab %}

{% tab post_llm_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_llm_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_llm_MiniMax_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

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"
}
```
{% endtab %}

{% tab post_llm_MiniMax_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_llm_MiniMax_example %}

{% tab post_llm_MiniMax_example 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": "…"}'
```
{% endtab %}

{% tab post_llm_MiniMax_example 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});
```
{% endtab %}

{% tab post_llm_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/agent-create
parent: MiniMax API v1
nav_order: 501
---
## Create a video using an agent template
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<small>June 30, 2025 (August 21, 2025)</small>

1. TOC
{:toc}

---

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](../start-here/setup-minimax) for details.

To browse available templates use [GET videos/agent-templates](../api-minimax-v1/get-minimax-videos-agent-templates).

{: .post }
> **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](../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](../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](../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`](../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](../api-minimax-v1/post-minimax-files) 
    * fileID of previously uploaded image retrieved via [GET /files](../api-minimax-v1/get-minimax-files) 
    * fileID of previously uploaded character retrieved via [GET videos/characters](../api-minimax-v1/get-minimax-videos-characters)
    * fileID of image generated via [POST images/create](../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.  

- `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](../api-minimax-v1/get-minimax-accounts-account) will be used.  
  Valid range: 1…10.  

##### Responses 

{% tabs post_videos-agent-create_MiniMax_response %}

{% tab post_videos-agent-create_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

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`](../api-minimax-v1/get-minimax-videos-videoId).

{% endtab %}

{% tab post_videos-agent-create_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_videos-agent-create_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_videos-agent-create_MiniMax_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_videos-agent-create_MiniMax_example %}

{% tab post_videos-agent-create_MiniMax_example 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>

{% endtab %}

{% tab post_videos-agent-create_MiniMax_example 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>

{% endtab %}

{% tab post_videos-agent-create_MiniMax_example 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
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/cancel
parent: MiniMax API v1
nav_order: 900
---
## Cancel the currently generated video
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<small>January 9, 2025</small>

1. TOC
{:toc}

---

Attempt to cancel a currently generated video created via [POST videos/create](../api-minimax-v1/post-minimax-videos-create).

{: .post }
> **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](../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 

{% tabs post_MiniMax_videos-cancel_response %}

{% tab post_MiniMax_videos-cancel_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

{% endtab %}

{% tab post_MiniMax_videos-cancel_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_MiniMax_videos-cancel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_MiniMax_videos-cancel_example %}

{% tab post_MiniMax_videos-cancel_example 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": "…"}'
```
{% endtab %}

{% tab post_MiniMax_videos-cancel_example 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});
```
{% endtab %}

{% tab post_MiniMax_videos-cancel_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create
parent: MiniMax API v1
nav_order: 500
---
## Create a video using a text and image prompt
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<small>September 25, 2024 (February 24, 2026)</small>

1. TOC
{:toc}

---

Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](../start-here/setup-minimax) for details.

To upload prompt image use [POST /files](../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 |

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

</details>

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax API account",
    "prompt": "Optional text prompt",
    "promptOptimization": true,
    "fileID": "user:user_id-minimax:account-file:file_id",
    "fileID2": "user:…-minimax:…-file:… (S2V models only)",
    "end_frame_fileID": "user:…-minimax:…-file:… (`02` 768p/1080p, `Veo-3.1`, `Veo-3.1-Fast`)",
    "model": "Optional model name",
    "options": "Optional option name",
    "aspectRatio": "16:9",
    "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](../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).

- `promptOptimization` is optional.
  Supported values: `true`, `false`. Default: `false` (no optimization).

- `fileID` — image/character reference. Upload via [POST /files](../api-minimax-v1/post-minimax-files), retrieve via [GET /files](../api-minimax-v1/get-minimax-files), [GET videos/characters](../api-minimax-v1/get-minimax-videos-characters), or use fileID from [POST images/create](../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` |

- `end_frame_fileID` is optional. The `end_frame_fileID` and `fileID` cannot be the same, reupload the end frame via [POST /files](../api-minimax-v1/post-minimax-files) if needed.

- `fileID2` … `fileID14` are optional, **for S2V models only** (`Veo-3.1-S2V`, `Veo-3.1-S2V-Fast`). Additional reference images for subject/character consistency. Requires `fileID` first. All files must belong to the same account.

- `aspectRatio` is optional, supported by `Sora-2`, `Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast`. Supported values: `16:9` (default), `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](https://www.minimax.io/platform/document/video_generation?key=66d1439376e52fcee2853049#whYrra7nHOP2eZy9yMMbnnU6))
  * `I2V-01-Director` image-to-video, camera movement control via `[<movement>]` in prompt ([instructions](https://www.minimax.io/platform/document/video_generation?key=66d1439376e52fcee2853049#whYrra7nHOP2eZy9yMMbnnU6))

  **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

- `options` is optional. Sets resolution and duration. Hailuo 01 models do not support `options`.

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

- `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](../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 

{% tabs post_videos-create_MiniMax_response %}

{% tab post_videos-create_MiniMax_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `videoId` to retrieve video status and results using [GET /videos/`videoId`](../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`](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>"
}
```

{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-6-second-long-video-using-text-prompt) 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"
}
```

{% endtab %}

{% tab post_videos-create_MiniMax_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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"
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_videos-create_MiniMax_example %}

{% tab post_videos-create_MiniMax_example 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": "…"}'
```
{% endtab %}

{% tab post_videos-create_MiniMax_example 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});
```
{% endtab %}

{% tab post_videos-create_MiniMax_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-wss">WSS</code> audio/wss
nav_order: 2010
nav_exclude: true
---
## Create text-to-speech audio stream over the WebSocket
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<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="https://useapi.net/docs/api-mureka-v1">Mureka API</a></b></span>

1. TOC
{:toc}

---

Use [POST audio/create-stream](../api-minimax-v1/post-minimax-audio-create-stream) to obtain `token` and `payload`.   
To see the provided below code in action use [Try It](../api-minimax-v1/post-minimax-audio-create-stream#try-it).  

{: .wss }
> **wss://api.useapi.net/v1/minimax/audio/wss?token=`token`**

##### Query Parameters

- `token` is **required**. Use [POST audio/create-stream](../api-minimax-v1/post-minimax-audio-create-stream) to obtain `token`.

##### Responses 

{% tabs wss-MiniMax_audio-wss_response %}

{% tab wss-MiniMax_audio-wss_response <span class="http-status-good">101</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101" rel="noreferrer" target="_blank"><span class="http-status-good">101 Switching Protocols</span></a> 

{% endtab %}

{% tab wss-MiniMax_audio-wss_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "<Error message>"
}
```

{% endtab %}

{% endtabs %}

##### 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](../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
---
layout: default
title: Setup Mureka
parent: Start Here
nav_order: 250
---
# <img style="height:1.2em;vertical-align: middle;" src="https://useapi.net/assets/images/mureka.webp"> Setup Mureka
{: .no_toc }

<small>December 2, 2024 (January 19, 2026)</small>

{: .note }
> Looking for the [legacy setup method](https://useapi.net/docs/start-here/setup-mureka-legacy)?

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 10 minutes to complete setup steps.</small>

---

{: .note }
> This is the setup guide for [Mureka API](../api-mureka-v1). A [Mureka AI](https://www.mureka.ai) account and a [useapi.net subscription](../subscription) are required for the API to work.

[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](../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="https://useapi.net/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
---
layout: default
title: Mureka API v1
nav_order: 7000
has_children: true
permalink: /docs/api-mureka-v1
---

# <img style="height:1.2em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: Mureka API v1
nav_order: 400
---
## Delete Mureka API account
{: .no_toc }

<small>December 2, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/mureka/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](post-mureka-accounts) request.

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

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

##### Responses 

{% tabs del_account_Mureka_response %}

{% tab del_account_Mureka_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_Mureka_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_Mureka_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_Mureka_example %}

{% tab del_account_Mureka_example 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> 
```
{% endtab %}

{% tab del_account_Mureka_example 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});
```
{% endtab %}

{% tab del_account_Mureka_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files/vocal
parent: Mureka API v1
nav_order: 2000
---
## Delete vocal
{: .no_toc }

<small>January 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Delete vocal which was uploaded using [POST files/vocal](../api-mureka-v1/post-mureka-files-vocal).

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../api-mureka-v1/get-mureka-music-vocals).

##### Responses 

{% tabs del_Mureka_files_response %}

{% tab del_Mureka_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_Mureka_files_example %}

{% tab del_Mureka_files_example 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>
```
{% endtab %}

{% tab del_Mureka_files_example 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});
```
{% endtab %}

{% tab del_Mureka_files_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files
parent: Mureka API v1
nav_order: 1850
---
## Delete track
{: .no_toc }

<small>December 13, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Delete track which was uploaded using [POST /files](../api-mureka-v1/post-mureka-files).

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../api-mureka-v1/get-mureka-files).

##### Responses 

{% tabs del_Mureka_files_response %}

{% tab del_Mureka_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_Mureka_files_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_Mureka_files_example %}

{% tab del_Mureka_files_example 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>
```
{% endtab %}

{% tab del_Mureka_files_example 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});
```
{% endtab %}

{% tab del_Mureka_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> music/<code class="language-plaintext highlighter-rouge">song_id</code>
parent: Mureka API v1
nav_order: 1500
---
## Delete song
{: .no_toc }

<small>December 2, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/mureka/music/`song_id`**

The `song_id` value returned by one of the following endpoints: 
* [GET /music](get-mureka-music)
* [POST /music/create](post-mureka-music-create)
* [POST /music/create-advanced](post-mureka-music-create-advanced)
* [POST /music/create-instrumental](post-mureka-music-create-instrumental)   

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

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

##### Responses 

{% tabs del_Mureka_music_song_id_response %}

{% tab del_Mureka_music_song_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{}
```
{% endtab %}

{% tab del_Mureka_music_song_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_Mureka_music_song_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_Mureka_music_song_id_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{}
```

##### Examples

{% tabs del_Mureka_music_song_id_example %}

{% tab del_Mureka_music_song_id_example 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> 
```
{% endtab %}

{% tab del_Mureka_music_song_id_example 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});
```
{% endtab %}

{% tab del_Mureka_music_song_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> speech/voice
parent: Mureka API v1
nav_order: 2400
---
## Delete speech voice
{: .no_toc }

<small>August 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices).

##### Responses 

{% tabs del_speech_voice_Mureka_speech_response %}

{% tab del_speech_voice_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{}
```
{% endtab %}

{% tab del_speech_voice_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_speech_voice_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_speech_voice_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_speech_voice_Mureka_speech_example %}

{% tab del_speech_voice_Mureka_speech_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/mureka/speech/voice?voice_id=12345678901234" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_speech_voice_Mureka_speech_example 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});
```
{% endtab %}

{% tab del_speech_voice_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> speech
parent: Mureka API v1
nav_order: 2170
---
## Delete speech
{: .no_toc }

<small>August 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](https://useapi.net/docs/api-mureka-v1/get-mureka-speech).

##### Responses 

{% tabs del_speech_Mureka_speech_response %}

{% tab del_speech_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{}
```
{% endtab %}

{% tab del_speech_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_speech_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_speech_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_speech_Mureka_speech_example %}

{% tab del_speech_Mureka_speech_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/mureka/speech/?id=23456789012345" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_speech_Mureka_speech_example 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});
```
{% endtab %}

{% tab del_speech_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
parent: Mureka API v1
nav_order: 200
---
## Retrieve Mureka API account configuration for `account` 
{: .no_toc }

<small>December 2, 2024 (January 20, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

[Setup Mureka](../../docs/start-here/setup-mureka)

{: .get }
> **https://api.useapi.net/v1/mureka/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](post-mureka-accounts) request.

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

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

##### Responses 

{% tabs get_account_Mureka_account_response %}

{% tab get_account_Mureka_account_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"
    }
}
```
{% endtab %}

{% tab get_account_Mureka_account_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_Mureka_account_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

Configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).

{% endtab %}

{% endtabs %}

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

{% tabs get_account_Mureka_account_example %}

{% tab get_account_Mureka_account_example Curl %}
``` bash
curl https://api.useapi.net/v1/mureka/accounts/<account> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_Mureka_account_example 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});
```
{% endtab %}

{% tab get_account_Mureka_account_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Mureka API v1
nav_order: 100
---
## Retrieve Mureka API accounts configuration
{: .no_toc }

<small>December 2, 2024 (January 20, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves the complete list of configured API accounts for Mureka.

[Setup Mureka](../../docs/start-here/setup-mureka)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_Mureka_response %}

{% tab account_Mureka_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"
  }
}
```
{% endtab %}

{% tab account_Mureka_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_Mureka_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST /accounts](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).

{% endtab %}

{% endtabs %}

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

{% tabs account_Mureka_example %}

{% tab account_Mureka_example Curl %}
``` bash
curl https://api.useapi.net/v1/mureka/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_Mureka_example 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});
```
{% endtab %}

{% tab account_Mureka_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files/youtube
parent: Mureka API v1
nav_order: 1700
---
## Retrieve soundtrack from YouTube url
{: .no_toc }

<small>December 13, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-mureka-v1/post-mureka-files).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_Mureka_files_youtube_response %}

{% tab get_Mureka_files_youtube_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
    "name": "<YouTube video name>",
    "cos_url": "https://...mp3",
    "duration": 21000
}
```
{% endtab %}

{% tab get_Mureka_files_youtube_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_Mureka_files_youtube_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_Mureka_files_youtube_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  name: string
  cos_url: string
  duration: number
}
```

##### Examples

{% tabs get_Mureka_files_youtube_example %}

{% tab get_Mureka_files_youtube_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/files/youtube/?account=account&url=<url>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_Mureka_files_youtube_example 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});
```
{% endtab %}

{% tab get_Mureka_files_youtube_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files
parent: Mureka API v1
nav_order: 1600
---
## Retrieve your reference tracks
{: .no_toc }

<small>December 13, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve full list of track uploaded using [POST /files](../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](../api-mureka-v1/post-mureka-music-create-advanced).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_Mureka_files_response %}

{% tab get_Mureka_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_Mureka_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_Mureka_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_Mureka_files_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_Mureka_files_example %}

{% tab get_Mureka_files_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/files/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_Mureka_files_example 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});
```
{% endtab %}

{% tab get_Mureka_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Mureka API v1
nav_order: 2460
---
## Retrieve Job Status
{: .no_toc }

<small>January 21, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-mureka-v1/post-mureka-music-create)
* [POST /music/create-instrumental](https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-instrumental)
* [POST /music/create-advanced](https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-advanced)
* [POST /music/extend](https://useapi.net/docs/api-mureka-v1/post-mureka-music-extend)
* [POST /music/regenerate](https://useapi.net/docs/api-mureka-v1/post-mureka-music-regenerate)
* [POST /speech](https://useapi.net/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](https://useapi.net/docs/api-mureka-v1/get-mureka-jobs).

{: .get }
> **https://api.useapi.net/v1/mureka/jobs/`jobid`**

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

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

##### Path Parameters

- `jobid` is **required**, the unique job identifier.

##### Responses

{% tabs get_mureka_jobs_jobid_response %}

{% tab get_mureka_jobs_jobid_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```

{% endtab %}

{% tab get_mureka_jobs_jobid_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

Invalid job ID format.

```json
{
  "error": "Invalid job ID: Missing required component"
}
```
{% endtab %}

{% tab get_mureka_jobs_jobid_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% tab get_mureka_jobs_jobid_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

Job belongs to a different user.

```json
{
  "error": "Unauthorized access to job"
}
```
{% endtab %}

{% tab get_mureka_jobs_jobid_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Job not found or has expired (jobs are retained for 7 days).

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

{% endtabs %}

##### Model

{% tabs get_mureka_jobs_jobid_model %}

{% tab get_mureka_jobs_jobid_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)
}
```

{% endtab %}

{% tab get_mureka_jobs_jobid_model 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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs get_mureka_jobs_jobid_examples %}

{% tab get_mureka_jobs_jobid_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
```
{% endtab %}

{% tab get_mureka_jobs_jobid_examples 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}`);
}
```
{% endtab %}

{% tab get_mureka_jobs_jobid_examples 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']}")
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs
parent: Mureka API v1
nav_order: 2450
---
## List Running Jobs
{: .no_toc }

<small>January 21, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **https://api.useapi.net/v1/mureka/jobs**

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

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

##### Responses

{% tabs get_mureka_jobs_response %}

{% tab get_mureka_jobs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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"
    ]
}
```

{% endtab %}

{% tab get_mureka_jobs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

Invalid API token.

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

{% endtabs %}

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

{% tabs get_mureka_jobs_example %}

{% tab get_mureka_jobs_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/jobs" \
  -H "Authorization: Bearer {API token}"
```
{% endtab %}

{% tab get_mureka_jobs_example 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}`);
  });
}
```
{% endtab %}

{% tab get_mureka_jobs_example 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']}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/moods-and-genres
parent: Mureka API v1
nav_order: 800
---
## Retrieve a list of supported Genres, Moods and Vocals
{: .no_toc }

<small>December 2, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_music_Mureka_music_moods-and-genres_response %}

{% tab get_music_Mureka_music_moods-and-genres_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
        }
    ]
}
```
{% endtab %}

{% tab get_music_Mureka_music_moods-and-genres_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_Mureka_music_moods-and-genres_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_Mureka_music_moods-and-genres_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    genres: { tag: string, cover?: string }[]
    moods: { tag: string }[]
    vocals: { tag: string }[]
}
```

##### Examples

{% tabs get_music_Mureka_music_moods-and-genres_example %}

{% tab get_music_Mureka_music_moods-and-genres_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/music/moods-and-genres/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_Mureka_music_moods-and-genres_example 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});
```
{% endtab %}

{% tab get_music_Mureka_music_moods-and-genres_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/refs
parent: Mureka API v1
nav_order: 1000
---
## Retrieve a list of reference songs
{: .no_toc }

<small>December 2, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../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](../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 

{% tabs get_music_Mureka_music_refs_response %}

{% tab get_music_Mureka_music_refs_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_music_Mureka_music_refs_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_Mureka_music_refs_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_Mureka_music_refs_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_music_Mureka_music_refs_example %}

{% tab get_music_Mureka_music_refs_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/music/refs/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_Mureka_music_refs_example 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});
```
{% endtab %}

{% tab get_music_Mureka_music_refs_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/<code class="language-plaintext highlighter-rouge">song_id</code>
parent: Mureka API v1
nav_order: 700
---
## Retrieve generated song lyrics and other details
{: .no_toc }

<small>December 2, 2024 (March 31, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/mureka/music/`song_id`**

The `song_id` value returned by one of the following endpoints: 
* [GET /music](get-mureka-music)
* [POST /music/create](post-mureka-music-create)
* [POST /music/create-advanced](post-mureka-music-create-advanced)
* [POST /music/create-instrumental](post-mureka-music-create-instrumental)   

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

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

##### Responses 

{% tabs get_music_Mureka_music_song_id_response %}

{% tab get_music_Mureka_music_song_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"    
}
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "The song has been deleted"
}
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_music_Mureka_music_song_id_example %}

{% tab get_music_Mureka_music_song_id_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/music/song_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_example 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});
```
{% endtab %}

{% tab get_music_Mureka_music_song_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/vocals
parent: Mureka API v1
nav_order: 900
---
## Retrieve a list of vocal samples including the ones you uploaded
{: .no_toc }

<small>December 2, 2024 (January 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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](../api-mureka-v1/post-mureka-files-vocal).  
  Supported values: `true`, `false` (default).

##### Responses 

{% tabs get_music_Mureka_music_vocals_response %}

{% tab get_music_Mureka_music_vocals_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_music_Mureka_music_vocals_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_Mureka_music_vocals_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_Mureka_music_vocals_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_music_Mureka_music_vocals_example %}

{% tab get_music_Mureka_music_vocals_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/music/vocals/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_Mureka_music_vocals_example 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});
```
{% endtab %}

{% tab get_music_Mureka_music_vocals_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music
parent: Mureka API v1
nav_order: 600
---
## Retrieve generated music
{: .no_toc }

<small>December 2, 2024 (March 31, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_music_Mureka_music_response %}

{% tab get_music_Mureka_music_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_music_Mureka_music_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_music_Mureka_music_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_music_Mureka_music_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_music_Mureka_music_example %}

{% tab get_music_Mureka_music_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/music/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_music_Mureka_music_example 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});
```
{% endtab %}

{% tab get_music_Mureka_music_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> profile
parent: Mureka API v1
nav_order: 450
---
## Retrieve your [mureka.ai](https://www.mureka.ai) account information and remaining credits
{: .no_toc }

<small>December 2, 2024 (April 4, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_profile_Mureka_profile_response %}

{% tab get_profile_Mureka_profile_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
        }
    }
}
```
{% endtab %}

{% tab get_profile_Mureka_profile_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_profile_Mureka_profile_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_profile_Mureka_profile_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_profile_Mureka_profile_example %}

{% tab get_profile_Mureka_profile_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/profile/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_profile_Mureka_profile_example 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});
```
{% endtab %}

{% tab get_profile_Mureka_profile_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/voices
parent: Mureka API v1
nav_order: 2200
---
## Retrieve speech voices
{: .no_toc }

<small>August 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_speech_voices_Mureka_speech_response %}

{% tab get_speech_voices_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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    
}
```
{% endtab %}

{% tab get_speech_voices_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_speech_voices_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_speech_voices_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_speech_voices_Mureka_speech_example %}

{% tab get_speech_voices_Mureka_speech_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_speech_voices_Mureka_speech_example 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});
```
{% endtab %}

{% tab get_speech_voices_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech
parent: Mureka API v1
nav_order: 2100
---
## Retrieve generated speech
{: .no_toc }

<small>August 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs get_speech_Mureka_speech_response %}

{% tab get_speech_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_speech_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_speech_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_speech_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs get_speech_Mureka_speech_example %}

{% tab get_speech_Mureka_speech_example Curl %}
``` bash
curl "https://api.useapi.net/v1/mureka/speech/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_speech_Mureka_speech_example 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});
```
{% endtab %}

{% tab get_speech_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/<code class="language-plaintext highlighter-rouge">account</code>
nav_exclude: true  
---
## Create or update Mureka API account configuration (Legacy)
{: .no_toc }

<small>December 2, 2024 (January 20, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .note }
> This is the legacy method that requires manual token renewal every 30 days. We recommend using [POST /accounts](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts) with Google cookies for **automatic token refresh**.

See [Setup Mureka (Legacy)](../start-here/setup-mureka-legacy) for details.     

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Mureka account",
    "token": "Mureka token",
}
```
- `account` and `token` are **required**. Please see [Setup Mureka](../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 

{% tabs post_account_Mureka_response %}

{% tab post_account_Mureka_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a> 

```json
{
    "updated": 1724514995,
    "account": "123456789",
    "token": "<token>",
    "updatedUTC": "2024-10-24T15:56:35.000Z",
    "email": "user@gmail.com"
}
```

{% endtab %}

{% tab post_account_Mureka_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_account_Mureka_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript, all fields are optional
  account: string
  token: string
  updated: number
  updatedUTC: string
  email?: string
  error: string
  code: number
}
```

##### Examples

{% tabs post_account_Mureka_example %}

{% tab post_account_Mureka_example 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": "…"}'
```
{% endtab %}

{% tab post_account_Mureka_example 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});
```
{% endtab %}

{% tab post_account_Mureka_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: Mureka API v1
nav_order: 299
---
## Configure Mureka API account with auto-refresh
{: .no_toc }

<small>January 19, 2026 (January 20, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../start-here/setup-mureka) for detailed instructions.

{: .note }
> Looking for the [legacy method](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts-account) with manual token setup?

{: .post }
> **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](../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

{% tabs post_account_Mureka_session_response %}

{% tab post_account_Mureka_session_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
        }
    }
}
```

{% endtab %}

{% tab post_account_Mureka_session_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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
}
```
{% endtab %}

{% tab post_account_Mureka_session_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### 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](../start-here/setup-mureka) with fresh cookies.

##### Examples

{% tabs post_account_Mureka_session_example %}

{% tab post_account_Mureka_session_example 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"}}'
```
{% endtab %}

{% tab post_account_Mureka_session_example 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});
```
{% endtab %}

{% tab post_account_Mureka_session_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files/motif
parent: Mureka API v1
nav_order: 1900
---

## Upload mp3 melody (motif) track 
{: .no_toc }

<small>December 13, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](../api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs post_files_Mureka_v1_files_response %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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](../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
}
```

{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: string
  url: string
  duration_milliseconds: number
}
```

##### Examples

{% tabs post_files_Mureka_v1_files_example %}

{% tab post_files_Mureka_v1_files_example 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
```
{% endtab %}

{% tab post_files_Mureka_v1_files_example 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});
```
{% endtab %}

{% tab post_files_Mureka_v1_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files/vocal
parent: Mureka API v1
nav_order: 1950
---

## Upload mp3 vocal
{: .no_toc }

<small>January 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs post_Mureka_v1_files_vocal_response %}

{% tab post_Mureka_v1_files_vocal_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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](../api-mureka-v1/post-mureka-music-create-advanced).

```json
{
  "id": 1234567890,
  "title": "vocal name",
  "url": "https://<vocal download url>.mp3",
  "duration_milliseconds": 50000
}
```

{% endtab %}

{% tab post_Mureka_v1_files_vocal_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_Mureka_v1_files_vocal_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_v1_files_vocal_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: number
  title: string
  url: string
  duration_milliseconds: number
}
```

##### Examples

{% tabs post_Mureka_v1_files_vocal_example %}

{% tab post_Mureka_v1_files_vocal_example 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
```
{% endtab %}

{% tab post_Mureka_v1_files_vocal_example 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});
```
{% endtab %}

{% tab post_Mureka_v1_files_vocal_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files
parent: Mureka API v1
nav_order: 1800
---
## Upload mp3 audio track to your music collection
{: .no_toc }

<small>December 13, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-mureka-v1/get-mureka-files).

[POST raw content using Make.com and similar nocode tools.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../start-here/setup-useapi) for details.   
- `Content-Type` is **required**, only `audio/mpeg ` supported.

##### Query Parameters

- `account` is optional when only one [account](../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](../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](../api-mureka-v1/get-mureka-music-moods-and-genres).

- `url` is optional. Provide the original YouTube url if applicable.

##### Responses 

{% tabs post_files_Mureka_v1_files_response %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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](../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"
}
```

{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_files_Mureka_v1_files_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  id: number
  url: string
  duration_milliseconds: number
  mood: string
  title: string
  genre: string
}
```

##### Examples

{% tabs post_files_Mureka_v1_files_example %}

{% tab post_files_Mureka_v1_files_example 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
```
{% endtab %}

{% tab post_files_Mureka_v1_files_example 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});
```
{% endtab %}

{% tab post_files_Mureka_v1_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create-advanced
parent: Mureka API v1
nav_order: 1200
---
## Create a song using custom lyrics, styles, vocals and reference song 
{: .no_toc }

<small>December 2, 2024 (April 4, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](../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](../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](../api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](../api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](../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](../api-mureka-v1/post-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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_Mureka_music_create-advanced_response %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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>"
        }
    ]
}
```

{% endtab %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_create-advanced_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_music_create_advanced_model %}

{% tab post_Mureka_music_create_advanced_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_music_create_advanced_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create_advanced_model <span class="http-status-bad">Error</span> %}

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
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_Mureka_music_create-advanced_example %}

{% tab post_Mureka_music_create-advanced_example 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": "…"}'
```
{% endtab %}

{% tab post_Mureka_music_create-advanced_example 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});
```
{% endtab %}

{% tab post_Mureka_music_create-advanced_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create-instrumental
parent: Mureka API v1
nav_order: 1210
---
## Create instrumental music
{: .no_toc }

<small>March 31, 2025 (April 4, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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](../api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](../api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](../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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_Mureka_music_create-instrumental_response %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```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>"
        }
    ]
}
```

{% endtab %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_create-instrumental_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_music_create_instrumental_model %}

{% tab post_Mureka_music_create_instrumental_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_music_create_instrumental_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create_instrumental_model <span class="http-status-bad">Error</span> %}

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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_Mureka_music_create-instrumental_example %}

{% tab post_Mureka_music_create-instrumental_example 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": "…"}'
```
{% endtab %}

{% tab post_Mureka_music_create-instrumental_example 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});
```
{% endtab %}

{% tab post_Mureka_music_create-instrumental_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create
parent: Mureka API v1
nav_order: 1100
---
## Create a song using AI-generated lyrics based on your prompt
{: .no_toc }

<small>December 2, 2024 (April 4, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_Mureka_music_create_response %}

{% tab post_Mureka_music_create_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```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>"
        }
    ]
}
```

{% endtab %}

{% tab post_Mureka_music_create_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Music generation is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_create_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_create_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_create_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_music_create_model %}

{% tab post_Mureka_music_create_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_music_create_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_music_create_model <span class="http-status-bad">Error</span> %}

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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_Mureka_music_create_example %}

{% tab post_Mureka_music_create_example 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": "…"}'
```
{% endtab %}

{% tab post_Mureka_music_create_example 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});
```
{% endtab %}

{% tab post_Mureka_music_create_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/download
parent: Mureka API v1
nav_order: 1220
---
## Download the song license and stems
{: .no_toc }

<small>March 31, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](get-mureka-music)
  * [POST /music/create](post-mureka-music-create)
  * [POST /music/create-advanced](post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](post-mureka-music-create-instrumental)   
  * [POST /music/download](post-mureka-music-download)
  * [POST /music/regenerate](post-mureka-music-regenerate)

- `type` is **required**. Supported values: `stem`, `license`
  
##### Responses 

{% tabs post_Mureka_music_download_response %}

{% tab post_Mureka_music_download_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```json
{
    "oss_key": "https://static-cos.mureka.ai/…zip",
    "paid_state": 1
}
```

{% endtab %}

{% tab post_Mureka_music_download_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_download_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_download_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  oss_key: string
  paid_state: number
}
```

##### Examples

{% tabs post_Mureka_music_download_example %}

{% tab post_Mureka_music_download_example 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"}'
```
{% endtab %}

{% tab post_Mureka_music_download_example 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});
```
{% endtab %}

{% tab post_Mureka_music_download_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/extend
parent: Mureka API v1
nav_order: 1230
---
## Extend song
{: .no_toc }

<small>December 13, 2024 (January 21, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](get-mureka-music)
  * [POST /music/create](post-mureka-music-create)
  * [POST /music/create-advanced](post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](post-mureka-music-create-instrumental)    
  * [POST /music/extend](post-mureka-music-extend)
  * [POST /music/regenerate](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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_Mureka_music_extend_response %}

{% tab post_Mureka_music_extend_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```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>"
        }
    ]
}
```

{% endtab %}

{% tab post_Mureka_music_extend_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Music extension is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_Mureka_music_extend_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_extend_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_extend_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_extend_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_music_extend_model %}

{% tab post_Mureka_music_extend_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_music_extend_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_music_extend_model <span class="http-status-bad">Error</span> %}

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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_Mureka_music_extend_example %}

{% tab post_Mureka_music_extend_example 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": "…"}'
```
{% endtab %}

{% tab post_Mureka_music_extend_example 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});
```
{% endtab %}

{% tab post_Mureka_music_extend_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/lyrics-generate
parent: Mureka API v1
nav_order: 1300
---
## Create an AI-generated lyrics based on your prompt
{: .no_toc }

<small>December 2, 2024 (October 3, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](../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 

{% tabs post_Mureka_music_lyrics-generate_response %}

{% tab post_Mureka_music_lyrics-generate_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```json
{
    "lyrics": "<lyrics generated by AI based on your optional prompt>"
}
```

{% endtab %}

{% tab post_Mureka_music_lyrics-generate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_lyrics-generate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_lyrics-generate_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```
{% endtab %}

{% tab post_Mureka_music_lyrics-generate_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_Mureka_music_lyrics-generate_example %}

{% tab post_Mureka_music_lyrics-generate_example 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": "…"}'
```
{% endtab %}

{% tab post_Mureka_music_lyrics-generate_example 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});
```
{% endtab %}

{% tab post_Mureka_music_lyrics-generate_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/regenerate
parent: Mureka API v1
nav_order: 1250
---
## Regenerate song
{: .no_toc }

<small>December 13, 2024 (January 21, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](get-mureka-music)
  * [POST /music/create](post-mureka-music-create)
  * [POST /music/create-advanced](post-mureka-music-create-advanced)
  * [POST /music/create-instrumental](post-mureka-music-create-instrumental)   
  * [POST /music/extend](post-mureka-music-extend)
  * [POST /music/regenerate](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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_Mureka_music_regenerate_response %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```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>"
        }
    ]
}
```

{% endtab %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Music regeneration is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_regenerate_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_music_regenerate_model %}

{% tab post_Mureka_music_regenerate_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_music_regenerate_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_music_regenerate_model <span class="http-status-bad">Error</span> %}

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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_Mureka_music_regenerate_example %}

{% tab post_Mureka_music_regenerate_example 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": …}'
```
{% endtab %}

{% tab post_Mureka_music_regenerate_example 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});
```
{% endtab %}

{% tab post_Mureka_music_regenerate_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/video-generate
parent: Mureka API v1
nav_order: 1400
---
## Create an AI-generated video for your song
{: .no_toc }

<small>December 2, 2024 (October 3, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](get-mureka-music)
  * [POST /music/create](post-mureka-music-create)
  * [POST /music/create-advanced](post-mureka-music-create-advanced)

##### Responses 

{% tabs post_Mureka_music_video-generate_response %}

{% tab post_Mureka_music_video-generate_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```json
{
    "video_url": "https://<download link>.mp4",
    "video_cover_url": "https://<cover image>.png",
    "video_id": 112233445566
}
```

{% endtab %}

{% tab post_Mureka_music_video-generate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Mureka_music_video-generate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Wrong username/password combination.",
  "code": 401
}
```
{% endtab %}

{% tab post_Mureka_music_video-generate_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

* 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)"
}
```
{% endtab %}

{% tab post_Mureka_music_video-generate_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript, all fields are optional
    video_url: string
    video_cover_url: string
    video_id: number
    error?: string
    code?: number
    msg?: string
}
```

##### Examples

{% tabs post_Mureka_music_video-generate_example %}

{% tab post_Mureka_music_video-generate_example 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": …}'
```
{% endtab %}

{% tab post_Mureka_music_video-generate_example 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});
```
{% endtab %}

{% tab post_Mureka_music_video-generate_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/voice
parent: Mureka API v1
nav_order: 2300
---
## Clone voice for speech
{: .no_toc }

<small>August 18, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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.

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](../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 

{% tabs post_speech_voice_Mureka_speech_response %}

{% tab post_speech_voice_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab post_speech_voice_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_speech_voice_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_speech_voice_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

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

{% tabs post_speech_voice_Mureka_speech_example %}

{% tab post_speech_voice_Mureka_speech_example 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
```
{% endtab %}

{% tab post_speech_voice_Mureka_speech_example 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});
```
{% endtab %}

{% tab post_speech_voice_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech ===
Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech
parent: Mureka API v1
nav_order: 2150
---
## Generate speech
{: .no_toc }

<small>August 18, 2025 (January 21, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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.

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body

- `account` is optional when only one [account](../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](https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices).  
  To create a cloned voice, first use [POST /speech/voice](https://useapi.net/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`](https://useapi.net/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`](https://useapi.net/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 

{% tabs post_speech_Mureka_speech_response %}

{% tab post_speech_Mureka_speech_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab post_speech_Mureka_speech_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>

Job created in async mode (`async: true`). Speech generation is processing in the background.

Use [GET /jobs/`jobid`](https://useapi.net/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"
    }
}
```

{% endtab %}

{% tab post_speech_Mureka_speech_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_speech_Mureka_speech_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_speech_Mureka_speech_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Account Error</span>

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](https://useapi.net/docs/api-mureka-v1/post-mureka-accounts).
{% endtab %}

{% endtabs %}

##### Model

{% tabs post_Mureka_speech_model %}

{% tab post_Mureka_speech_model <span class="http-status-good">200</span> 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
}
```

{% endtab %}

{% tab post_Mureka_speech_model <span class="http-status-good">201</span> Created (Async) %}

Job created and processing in background. Structure matches [GET /jobs/`jobid`](https://useapi.net/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
    }
}
```

{% endtab %}

{% tab post_Mureka_speech_model <span class="http-status-bad">Error</span> %}

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)
}
```

{% endtab %}

{% endtabs %}

##### Examples

{% tabs post_speech_Mureka_speech_example %}

{% tab post_speech_Mureka_speech_example 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
   }'
```
{% endtab %}

{% tab post_speech_Mureka_speech_example 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});
```
{% endtab %}

{% tab post_speech_Mureka_speech_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/start-here/setup-pixverse ===
Document URL: https://useapi.net/docs/start-here/setup-pixverse
---
layout: default
title: Setup PixVerse
parent: Start Here
nav_order: 400
---
# <img style="height:1.3em;vertical-align: bottom;" src="https://useapi.net/assets/images/pixverse.png"> Setup PixVerse
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 2 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [PixVerse API](../api-pixverse-v2). An active [PixVerse.ai](https://pixverse.ai) account and a [useapi.net subscription](../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`](../api-pixverse-v2/post-pixverse-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful.

## <code class="language-plaintext highlighter-rouge">OPTIONAL</code> 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`](../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="https://useapi.net/assets/images/pixverse_setup_v2-token.png">
</details>

* [POST /accounts/`email`](../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-v1 ===
Document URL: https://useapi.net/docs/api-pixverse-v1
---
layout: default
title: PixVerse API v1
nav_order: 470
has_children: true
permalink: /docs/api-pixverse-v1
nav_exclude: true
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

# <img style="height:1.3em;vertical-align: bottom;" src="https://useapi.net/assets/images/pixverse.png"> PixVerse API v1 
<small>June 2024</small>

This is an [experimental](../../docs/legal) API for the [PixVerse Discord Bot](https://discord.com/invite/MXHErdJHMg) by [PixVerse.AI](https://pixverse.ai/). PixVerse currently supports text and image inputs for generating 4-second-long videos. The available video styles include Realistic, Anime, and 3D Animation. For the Anime style you can reference one of the [anime characters](https://pixverse.notion.site/Available-Characters-for-Anime-Style-6648259c5db146be9e35509bfb9a3c86). PixVerse can also create a [meme face](https://pixverse.notion.site/Use-Meme_face-To-Create-Videos-With-The-Face-You-Upload-c6399111aced4b0aa04cb456bc3866d2) video from a provided image.

Official documentation links:
- [Discord support channel](https://discord.com/channels/1140860020586713128/1175986593996222565) 
- [PixVerse Discord tutorial](https://pixverse.notion.site/Discord-Tutorial-0bab659922ba471ab4f1d93edb2c61dd)

#### Example source code on GitHub 
* [Create breath-taking videos with PixVerse AI](https://github.com/useapi/examples/tree/main/pixverse-demo) June 10, 2024


=== URL: https://useapi.net/docs/api-pixverse-v1/del-pixverse-account-channel ===
Document URL: https://useapi.net/docs/api-pixverse-v1/del-pixverse-account-channel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> pixverse/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: PixVerse API v1
nav_order: 400
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## Delete PixVerse account
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/pixverse/account/`channel`**

The `channel` value should correspond to an account configured previously via a [POST](post-pixverse-account-channel) request.

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

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

##### Responses 

{% tabs del_account_PixVerse_response %}

{% tab del_account_PixVerse_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_PixVerse_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_PixVerse_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_PixVerse_example %}

{% tab del_account_PixVerse_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/pixverse/account/<channel> 
```
{% endtab %}

{% tab del_account_PixVerse_example JavaScript %}
``` javascript
const channel = "Previously configured channel id"; 
const apiUrl = `https://api.useapi.net/v1/pixverse/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});
```
{% endtab %}

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

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-account-channel ===
Document URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-account-channel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> pixverse/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: PixVerse API v1
nav_order: 200
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.


## Retrieve PixVerse configuration for `channel` 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/pixverse/account/`channel`**

The `channel` value should correspond to an account configured previously via a [POST](post-pixverse-account-channel) request.

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

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

##### Responses 

{% tabs get_account_PixVerse_channel_response %}

{% tab get_account_PixVerse_channel_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "server": "Discord server id",
  "channel": "Discord channel id",
  "discord": "Discord token",
  "maxJobs": 1-10
}
```
{% endtab %}

{% tab get_account_PixVerse_channel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_PixVerse_channel_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

Configuration not found. To create configuration use [pixverse/account/`channel`](https://useapi.net/docs/api-pixverse-v1/post-pixverse-account-channel).

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs get_account_PixVerse_channel_example %}

{% tab get_account_PixVerse_channel_example Curl %}
``` bash
curl https://api.useapi.net/v1/pixverse/account/<channel> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

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

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

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-account ===
Document URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-account
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> pixverse/account
parent: PixVerse API v1
nav_order: 100
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## Retrieve PixVerse accounts information
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

For your convenience, you can specify your [PixVerse configuration](../start-here/setup-pixverse) 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 Discord / PixVerse.

This endpoint retrieves the complete list of configured accounts for PixVerse.

{: .get }
> **https://api.useapi.net/v1/pixverse/account**

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

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

##### Responses 

{% tabs account_PixVerse_response %}

{% tab account_PixVerse_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
    "Discord channel A": {
        "server": "Discord server A",
        "channel": "Discord channel A",
        "discord": "Discord token A",
        "maxJobs": 1-10
    },
    "Discord channel B": {
        "server": "Discord server B",
        "channel": "Discord channel B",
        "discord": "Discord token B",
        "maxJobs": 1-10
    },
    "Discord channel N": {
        "server": "Discord server N",
        "channel": "Discord channel N",
        "discord": "Discord token N",
        "maxJobs": 1-10
    }    
}
```
{% endtab %}

{% tab account_PixVerse_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_PixVerse_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [pixverse/account/`channel`](https://useapi.net/docs/api-pixverse-v1/post-pixverse-account-channel).

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs account_PixVerse_example %}

{% tab account_PixVerse_example Curl %}
``` bash
curl https://api.useapi.net/v1/pixverse/account \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

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

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

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobid ===
Document URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: PixVerse API v1
nav_order: 1000
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## Retrieve PixVerse job status and results
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of 
- [pixverse/create](../api-pixverse-v1/post-pixverse-create)
- [pixverse/animate](../api-pixverse-v1/post-pixverse-animate)
- [pixverse/create_single](../api-pixverse-v1/post-pixverse-create_single)
- [pixverse/meme_face](../api-pixverse-v1/post-pixverse-meme_face)
- [pixverse/button](../api-pixverse-v1/post-pixverse-button)

If you specified optional parameter [`replyUrl`](../api-pixverse-v1/post-pixverse-create#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 PixVerse, 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.

{: .get }
> **https://api.useapi.net/v1/pixverse/jobs/?jobid=`jobid`**

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

##### Query Parameter
`jobid` is **required**, use value returned by 
- [pixverse/create](../api-pixverse-v1/post-pixverse-create)
- [pixverse/animate](../api-pixverse-v1/post-pixverse-animate)
- [pixverse/create_single](../api-pixverse-v1/post-pixverse-create_single)
- [pixverse/meme_face](../api-pixverse-v1/post-pixverse-meme_face)
- [pixverse/button](../api-pixverse-v1/post-pixverse-button)

##### Responses 
{:toc}

{% tabs get_pixverse_jobid_response %}

{% tab get_pixverse_jobid_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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 video from `attachments` field. Field `content` contains message generated by PixVerse reflecting current generation parameters and progress. Optional array `embeds` contains additional information.  

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-create_single",
    "status": "completed",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:19:20.256Z",
    "prompt": "Sun breaking through clouds over the beautiful view of San Francisco",
    "buttons": [ "U1", "U2", "U3", "U4", "V1", "V2", "V3", "V4", "ReDo"],
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 10,
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> (prompt: Sun breaking through clouds over the beautiful view of San Francisco style: Realistic aspect-ratio: 16:9) Author: <@Discord user id>)",
    "timestamp": "2023-09-09T02:05:24.991000+00:00",
    "attachments": [
        {
            "url": "<generated video url>",
            "proxy_url": "<generated proxy video url>",
            "width": 768,
            "height": 768,
            "content_type": "<generated video type>",
            "id": "<Discord attachment id>",
            "filename": "<generated video filename>",
            "size": 7204115
        }
    ],
    "code": 200
}
```
{% endtab %}

{% tab get_pixverse_jobid_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% tab get_pixverse_jobid_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab get_pixverse_jobid_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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


{% tab get_pixverse_jobid_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% tab get_pixverse_jobid_response <span class="http-status-bad">410</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

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

{% endtab %}

{% endtabs %}

##### Model
```typescript
{ // TypeScript, all fields are optional
  jobid: string,
  parentJobId: string,
  verb: 'pixverse-create' | 'pixverse-animate' | 'pixverse-create_single' | 'pixverse-meme_face' | 'pixverse-button',
  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,
  negative_prompt: string,
  motion: number,
  seed_value: number,
  image: { size: number, type: string  },
  face: { size: number, type: string  },
  button: 'U1' | 'U2' | 'U3' | 'U4' | 'V1' | 'V2' | 'V3' | 'V4' | 'ReDo' | '🔄' | '🔀' | '⏫',
  buttons: [ 'U1', 'U2', 'U3', 'U4', 'V1', 'V2', 'V3', 'V4', 'ReDo', '🔄', '🔀', '⏫' ],
  style: 'Realistic' | 'Anime' | '3D Animation',
  aspect_ratio: '16:9' | '9:16' | '1:1' | '4:3' | '3:4',
  character: 'eula' | 'ganyu' | 'hutao' | 'kamisatoayaka' | 'keqing' | 'klee' | 'nahida' | 'ningguang' | 'raidenshogun' | 'xiangling' | 'yaemiko',
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  maxJobs: number,
  messageId: string,
  content: string, // Contains message generated by PixVerse 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

{% tabs pixverse_jobid_example %}

{% tab pixverse_jobid_example Curl %}
``` bash
curl https://api.useapi.net/v1/pixverse/jobs/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab pixverse_jobid_example JavaScript %}
``` javascript
const token = "API token";
const jobid = "jobid returned by pixverse/create, pixverse/animate, pixverse/create_single, pixverse/meme_face or pixverse/button";      
const apiUrl = `https://api.useapi.net/v1/pixverse/jobs/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```
{% endtab %}

{% tab pixverse_jobid_example Python %}
``` python
import requests
token = "API token"
jobid = "jobid returned by pixverse/create, pixverse/animate, pixverse/create_single, pixverse/meme_face or pixverse/button"
apiUrl = f"https://api.useapi.net/v1/pixverse/jobs/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobs-cancel ===
Document URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobs-cancel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> …/cancel/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: PixVerse API v1
nav_order: 2000
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.


## Cancel PixVerse job
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Cancel execution of job created by 
- [pixverse/create](../api-pixverse-v1/post-pixverse-create)
- [pixverse/animate](../api-pixverse-v1/post-pixverse-animate)
- [pixverse/create_single](../api-pixverse-v1/post-pixverse-create_single)
- [pixverse/meme_face](../api-pixverse-v1/post-pixverse-meme_face)
- [pixverse/button](../api-pixverse-v1/post-pixverse-button)

{: .get }
> **https://api.useapi.net/v1/pixverse/jobs/cancel/?jobid=`jobid`**

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

##### Query Parameter
`jobid` is **required**, use value returned by 
- [pixverse/create](../api-pixverse-v1/post-pixverse-create)
- [pixverse/animate](../api-pixverse-v1/post-pixverse-animate)
- [pixverse/create_single](../api-pixverse-v1/post-pixverse-create_single)
- [pixverse/meme_face](../api-pixverse-v1/post-pixverse-meme_face)
- [pixverse/button](../api-pixverse-v1/post-pixverse-button)

##### Responses 
{:toc}

{% tabs post_pika_cancel_response %}

{% tab post_pika_cancel_response <span class="http-status-good">200</span> %}

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

{% endtab %}

{% tab post_pika_cancel_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% endtab %}

{% tab post_pika_cancel_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_pika_cancel_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}


{% tab post_pika_cancel_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs pika_cancel_example %}

{% tab pika_cancel_example Curl %}
``` bash
curl https://api.useapi.net/v1/pixverse/jobs/cancel/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab pika_cancel_example JavaScript %}
``` javascript
const token = "API token";
const jobid = "jobid returned by pixverse/create, pixverse/animate, pixverse/encrypt_text, pixverse/encrypt_image or pixverse/button";      
const apiUrl = `https://api.useapi.net/v1/pixverse/jobs/cancel/?jobid=${jobid}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```
{% endtab %}

{% tab pika_cancel_example Python %}
``` python
import requests
token = "API token"
jobid = "jobid returned by pixverse/create, pixverse/animate, pixverse/encrypt_text, pixverse/encrypt_image or pixverse/button"
apiUrl = f"https://api.useapi.net/v1/pixverse/jobs/cancel/?jobid={jobid}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobs ===
Document URL: https://useapi.net/docs/api-pixverse-v1/get-pixverse-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> pixverse/jobs
parent: PixVerse API v1
nav_order: 3000
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.


## Get list of currently executing PixVerse jobs
{: .no_toc }
 
## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/pixverse/jobs**

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

##### Responses 
{:toc}

{% tabs post_pika_jobs_response %}

{% tab post_pika_jobs_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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

{% endtab %}

{% tab post_pika_jobs_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_pika_jobs_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs pika_jobs_example %}

{% tab pika_jobs_example Curl %}
``` bash
curl https://api.useapi.net/v1/pixverse/jobs \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

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

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

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-account-channel ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-account-channel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/account/<code class="language-plaintext highlighter-rouge">channel</code>
parent: PixVerse API v1
nav_order: 300
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## Create or update PixVerse account information
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

For your convenience, you can specify your [PixVerse configuration](../start-here/setup-pixverse) 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 Discord / PixVerse.

{: .post }
> **https://api.useapi.net/v1/pixverse/account/`channel`**

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

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

##### Request Body
```json
{
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id",
    "maxJobs": 1-10,
}
```
- `discord`, `server`, `channel` are **required**. Please see [Setup PixVerse](../start-here/setup-pixverse) for details. 

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

- `maxJobs` is **required**. Currently, it should be between 1 and 10.

##### Responses 

{% tabs post_account_PixVerse_response %}

{% tab post_account_PixVerse_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab post_account_PixVerse_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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 (<channel>) is not valid Discord channel id"
    "Required param channel (<channel>) not matching to /pixverse/account/<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
}
```
{% endtab %}

{% tab post_account_PixVerse_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_account_PixVerse_example %}

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

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

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

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-animate ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-animate
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/animate
parent: PixVerse API v1
nav_order: 700
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## PixVerse [/animate](https://pixverse.notion.site/Use-Animate-To-Bring-Your-Image-To-Life-cd92610a27644c368a59fdad972e8578) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the PixVerse [/animate](https://pixverse.notion.site/Use-Animate-To-Bring-Your-Image-To-Life-cd92610a27644c368a59fdad972e8578) command to your [Discord PixVerse private thread channel](../start-here/setup-pixverse). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../api-pixverse-v1/get-pixverse-jobid) endpoint.  

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

{: .post }
> **https://api.useapi.net/v1/pixverse/animate**

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

##### Request Body
```json
{
    "image": "Image (jpg/png/jpeg) File or Blob",
    "prompt": "Prompt",
    "motion": "Adjust the strength of motion in the content (1…10, default 5)",
    "seed_value": "Seed for the generation (0…2147483647)",
    "hd_quality": "Produces clearer & precise videos, but requires 1 to 2 times the longer generation time",
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id",
    "maxJobs": 10,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `image` is **required**, an image (jpg/png/jpeg) you want to animate. 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.

- `prompt` is optional, must contain PixVerse [/animate](https://pixverse.notion.site/Use-Animate-To-Bring-Your-Image-To-Life-cd92610a27644c368a59fdad972e8578) prompt.  
  Maximum length 512 characters.  

- `motion` is optional, adjust the strength of motion in the content.  
  Supported range 1…10, default 5.  

- `seed_value` is optional, seed for the generation.  
  Supported range 0…2147483647.   

- `hd_quality` is optional, produces clearer & precise videos, but requires 1 to 2 times the longer generation time.  
  Must be one of following values: `Yes`, `No`. 

- `discord`, `server`, `channel` are optional, if not provided randomly selected available account from [pixverse/account](../api-pixverse-v1/get-pixverse-account) will be used. See [Setup PixVerse](../start-here/setup-pixverse) for details.    
**Note** You may specify the `channel` value alone (omitting `discord` and `server`) when you wish to use a specific account from the configured list at [pixverse/account](../api-pixverse-v1/get-pixverse-account).

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 10.  

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_pixverse-animate_response %}

{% tab post_pixverse-animate_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve PixVerse job status and results](../api-pixverse-v1/get-pixverse-jobid). `content` contains message generated by PixVerse reflecting current generation parameters and progress.

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-animate",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "image": { "size": 1628384, "type": "image/png" },
    "prompt": "smiling and blinking",
    "motion": 5,
    "seed_value": 12345,
    "hd_quality": "No",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 10,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> We are making videos. We will notify you when it's done. ([image attached](<https://cdn.discordapp.com/ephemeral-attachments/…>) prompt: smiling and blinking motion: 5 HD Quality: None) Author: <@Discord user id>)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```
{% endtab %}

{% tab post_pixverse-animate_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "image, discord, server or channel value is missing"
      "prompt, replyRef or replyUrl is too long"
      "image is not File or Blob"
      "motion <motion> valid range 1-10, default 5"
      "seed_value <seed_value> valid range 0-2147483647"
      "hd_quality <hd_quality> not supported, must be one of Yes,No"
    "code": 400
}
```
{% endtab %}


{% tab post_pixverse-animate_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_pixverse-animate_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_pixverse-animate_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params.

```json
{
    "error": "Apologies! Our AI moderator thinks this prompt or images as potentially violating our [community guidelines](<https://discord.com/channels/1140860020586713128/1168473004498501652>).",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

{% endtab %}

{% tab post_pixverse-animate_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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 [pixverse/animate](#pixverse-animate-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
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'pixverse-animate',
  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
  image: { size: number, type: string },
  prompt: string,
  motion: number,
  seed_value: number,
  hd_quality: 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,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by PixVerse reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

{% tabs pixverse-animate_example %}

{% tab pixverse-animate_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/pixverse/animate \
     -F "discord=<Discord token>" \
     -F "server=<Discord server id>" \
     -F "channel=<Discord channel id>" \
     -F 'image=@"<Path to the image>"' \
     -F "prompt=<PixVerse prompt>" 
```
{% endtab %}

{% tab pixverse-animate_example JavaScript %}
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/pixverse/animate";
    const token = "API token";
    const prompt = "PixVerse prompt";
    const discord = "Discord token";
    const server = "Discord server";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("prompt", prompt);
    formData.append("discord", discord);
    formData.append("server", server);
    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 = "./pixverse.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("image", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="pixverse-animate-image-url" type="file"> 
        const imageFile = document.getElementById(`pixverse-animate-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()
```
{% endtab %}

{% tab pixverse-animate_example Python %}
``` python
import requests

api_url = "https://api.useapi.net/v1/pixverse/animate"
token = "API token"
prompt = "PixVerse prompt"
discord = "Discord token"
server = "Discord server"
channel = "Discord channel"

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

files = {
    'prompt': (None, prompt),
    'discord': (None, discord),
    'server': (None, server),
    '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 = "./pixverse.png"
# with open(image_file_path, 'rb') as image_file:
#     files['image'] = ('pixverse.png', image_file.read(), 'image/png')

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-button ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-button
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/button
parent: PixVerse API v1
nav_order: 900
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## PixVerse [button](https://pixverse.notion.site/How-to-Upscale-My-Video-489bd81762374dd892c90ea32eee4ef4) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the PixVerse [button](https://pixverse.notion.site/How-to-Upscale-My-Video-489bd81762374dd892c90ea32eee4ef4) command to your [Discord PixVerse channel](../start-here/setup-pixverse). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../api-pixverse-v1/get-pixverse-jobid) endpoint.  

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

{: .post }
> **https://api.useapi.net/v1/pixverse/button**

##### 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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "jobid": "jobid",
    "button": "button",
    "prompt": "optional prompt for buttons V1, V2, V3, V4 and 🔀",
    "discord": "Discord token",
    "maxJobs": 10,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `jobid` is **required**, `jobid` of successfully completed (`status` set to [*completed*](../api-pixverse-v1/get-pixverse-jobid#model) [pixverse/create](../api-pixverse-v1/post-pixverse-create), [pixverse/animate](../api-pixverse-v1/post-pixverse-animate), [pixverse/create_single](../api-pixverse-v1/post-pixverse-create_single), [pixverse/meme_face](../api-pixverse-v1/post-pixverse-meme_face) or [pixverse/button](../api-pixverse-v1/post-pixverse-button) job.

- `button` is **required**, button from buttons array of job referenced via `jobid` above, see [*button*](#model).

- `prompt` is optional, the buttons `V1`, `V2`, `V3`, `V4` and 🔀 accept a prompt. 

- `discord` is optional, if provided will override `discord` value of referenced above `jobid`, see [Setup PixVerse](../start-here/setup-pixverse) for details. If the `channel` corresponding to the `jobid` mentioned above has an account configured under [pixverse/account](../api-pixverse-v1/get-pixverse-account), 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.

- `maxJobs` is optional, if provided will override `maxJobs` value of referenced above `jobid`, if not provided defaulted to 10.  

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_pixverse-button_response %}

{% tab post_pixverse-button_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve PixVerse job status and results](../api-pixverse-v1/get-pixverse-jobid). `content` contains message generated by PixVerse reflecting current generation parameters and progress.

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-button",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "button": "V1",
    "prompt": "Sun breaking through clouds over the beautiful view of San Francisco",
    "parentJobId": "<jobid>",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 10,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id>  Hi! We are remaking your videos. We will notify you when it's done. (prompt: Sun breaking through clouds over the beautiful view of San Francisco style: Realistic negative-prompt: sand aspect-ratio: 16:9 character: kamisatoayaka) Author: <@Discord user id>)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```
{% endtab %}

{% tab post_pixverse-button_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "jobid or button value is missing"
      "button <button> not supported"
      "prompt, replyRef or replyUrl is too long"
      "button <button> does not support prompt"
    "code": 400
}
```
{% endtab %}


{% tab post_pixverse-button_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_pixverse-button_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_pixverse-button_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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 [pixverse/button](#pixverse-button-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
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'pixverse-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' |
          'ReDo' |
          '🔄' | '🔀' | '⏫',
  prompt: string,
  parentJobId: 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,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by PixVerse reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

{% tabs pixverse-button_example %}

{% tab pixverse-button_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/pixverse/button \
     -F "discord=<Discord token>" \
     -F "jobid=<Completed pixverse/… jobid>" \
     -F "button=<Button from buttons array of above jobid>" 
```
{% endtab %}

{% tab pixverse-button_example JavaScript %}
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/pixverse/button";
    const token = "API token";
    const jobid = "Completed pixverse/… jobid";
    const button = "Button from buttons array of above jobid";
    const discord = "Discord token";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("jobid", jobid);
    formData.append("button", button);
    formData.append("discord", discord);

    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```
{% endtab %}

{% tab pixverse-button_example Python %}
``` python
import requests

api_url = "https://api.useapi.net/v1/pixverse/button"
token = "API token"
jobid = "Completed pixverse/… jobid"
button = "Button from buttons array of above jobid"
discord = "Discord token"
channel = "Discord channel"

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

files = {
    'jobid': (None, jobid),
    'button': (None, button),
    'discord': (None, discord)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-create ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/create
parent: PixVerse API v1
nav_order: 500
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## PixVerse [/create](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the PixVerse [/create](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) command to your [Discord PixVerse private thread channel](../start-here/setup-pixverse). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../api-pixverse-v1/get-pixverse-jobid) endpoint.  

PixVerse [/create](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) will generate 4 videos at once, it is resource intense command. Currently we **do not recommend** executing more than two `/create` jobs at once. The PixVerse bot will most likely throttle you down with a `429`.

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

{: .post }
> **https://api.useapi.net/v1/pixverse/create**

##### 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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "prompt": "PixVerse prompt",
    "style": "The style of the video you want to create",
    "negative_prompt": "What you don't want to in the video",
    "aspect_ratio": "Aspect-ratio for the video",
    "character": "Character",
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id",
    "maxJobs": 10,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `prompt` is **required**, must contain PixVerse [/create](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) prompt.  
  Maximum length 512 characters.  

- `style` is **required**, must be one of following values:  
  `Realistic`  
  `Anime`  
  `3D Animation`  

- `negative_prompt` is optional.  
  Maximum length 512 characters.  

- `aspect_ratio` is optional, must be one of following values:  
  `16:9`  
  `9:16`  
  `1:1`  
  `4:3`  
  `3:4`  

- `character` is optional, used when style set to `Anime` otherwise ignored, must be one of [following values](https://pixverse.notion.site/Available-Characters-for-Anime-Style-6648259c5db146be9e35509bfb9a3c86):  
  `eula`  
  `ganyu`  
  `hutao`  
  `kamisatoayaka`  
  `keqing`  
  `klee`  
  `nahida`  
  `ningguang`  
  `raidenshogun`  
  `xiangling`  
  `yaemiko`  

- `discord`, `server`, `channel` are optional, if not provided randomly selected available account from [pixverse/account](../api-pixverse-v1/get-pixverse-account) will be used. See [Setup PixVerse](../start-here/setup-pixverse) for details.    
**Note** You may specify the `channel` value alone (omitting `discord` and `server` values) when you wish to use a specific account from the configured list at [pixverse/account](../api-pixverse-v1/get-pixverse-account).

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 10.  
  Currently we **do not recommend** executing more than two `/create` jobs at once. The PixVerse bot will most likely throttle you down with a `429`.

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_pixverse-create_response %}

{% tab post_pixverse-create_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve PixVerse job status and results](../api-pixverse-v1/get-pixverse-jobid). `content` contains message generated by PixVerse reflecting current generation parameters and progress.

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-create",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "prompt": "Milla Jovovich riding motorcycle in extreme stormy weather thru California desert",
    "style": "Realistic",
    "negative_prompt": "sand",
    "aspect_ratio": "16:9",
    "character": "kamisatoayaka",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 2,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> We are making videos. We will notify you when it's done. (prompt: Milla Jovovich riding motorcycle in extreme stormy weather thru California desert style: Realistic negative-prompt: sand aspect-ratio: 16:9 character: kamisatoayaka) Author: <@Discord user id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```
{% endtab %}

{% tab post_pixverse-create_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "prompt, discord, server or channel value is missing"
      "prompt, negative_prompt, replyRef or replyUrl is too long"
      "style is missing or empty"
      "style <style> not supported, must be one of <list of supported styles>"
      "aspect_ratio <aspect_ratio> not supported, must be one of <list of supported aspect ratios>"
      "character <character> not supported, must be one of <list of supported characters>"
    "code": 400
}
```
{% endtab %}


{% tab post_pixverse-create_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_pixverse-create_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_pixverse-create_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params.

```json
{
    "error": "Apologies! Our AI moderator thinks this prompt or images as potentially violating our [community guidelines](<https://discord.com/channels/1140860020586713128/1168473004498501652>).",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```
{% endtab %}

{% tab post_pixverse-create_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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 [pixverse/create](#pixverse-create-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
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'pixverse-create',
  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,
  style: string,
  negative_prompt: string,
  aspect_ratio: string,
  character: 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,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by PixVerse reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

{% tabs pixverse-create_example %}

{% tab pixverse-create_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/pixverse/create \
     -F "discord=<Discord token>" \
     -F "server=<Discord server id>" \
     -F "channel=<Discord channel id>" \
     -F "prompt=<PixVerse prompt>" \
     -F 'style="Realistic"'
```
{% endtab %}

{% tab pixverse-create_example JavaScript %}
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/pixverse/create";
    const token = "API token";
    const prompt = "PixVerse prompt";
    const style = "Realistic";
    const discord = "Discord token";
    const server = "Discord server";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };

    const formData = new FormData();
    formData.append("prompt", prompt);
    formData.append("style", style);
    formData.append("discord", discord);
    formData.append("server", server);
    formData.append("channel", channel);

    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```
{% endtab %}

{% tab pixverse-create_example Python %}
``` python
import requests

api_url = "https://api.useapi.net/v1/pixverse/create"
token = "API token"
prompt = "PixVerse prompt"
style = "Realistic"
discord = "Discord token"
server = "Discord server"
channel = "Discord channel"

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

files = {
    'prompt': (None, prompt),
    'style': (None, style),
    'discord': (None, discord),
    'server': (None, server),
    'channel': (None, channel)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-create_single ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-create_single
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/create_single
parent: PixVerse API v1
nav_order: 600
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## PixVerse [/create_single](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the PixVerse [/create_single](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) command to your [Discord PixVerse private thread channel](../start-here/setup-pixverse). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../api-pixverse-v1/get-pixverse-jobid) endpoint.  

PixVerse `/create_single` is similar to PixVerse [/create](https://useapi.net/docs/api-pixverse-v1/post-pixverse-create) but only generates one video and accepts an optional `seed_value` parameter.

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

{: .post }
> **https://api.useapi.net/v1/pixverse/create_single**

##### 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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "prompt": "PixVerse prompt",
    "style": "The style of the video you want to create",
    "negative_prompt": "What you don't want to in the video",
    "aspect_ratio": "Aspect-ratio for the video",
    "character": "Character",
    "seed_value": "Seed for the generation (0…2147483647)",
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id",
    "maxJobs": 10,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `prompt` is **required**, must contain PixVerse [/create_single](https://pixverse.notion.site/Use-Create-To-Generate-Videos-With-Text-Prompts-15d1e2971370474b927f6b7027fc5a56) prompt.  
  Maximum length 512 characters.  

- `style` is **required**, must be one of following values:  
  `Realistic`  
  `Anime`  
  `3D Animation`  

- `negative_prompt` is optional.  
  Maximum length 512 characters.  

- `aspect_ratio` is optional, must be one of following values:  
  `16:9`  
  `9:16`  
  `1:1`  
  `4:3`  
  `3:4`  

- `character` is optional, used when style set to `Anime` otherwise ignored, must be one of [following values](https://pixverse.notion.site/Available-Characters-for-Anime-Style-6648259c5db146be9e35509bfb9a3c86):  
  `eula`  
  `ganyu`  
  `hutao`  
  `kamisatoayaka`  
  `keqing`  
  `klee`  
  `nahida`  
  `ningguang`  
  `raidenshogun`  
  `xiangling`  
  `yaemiko`  

- `seed_value` is optional, seed for the generation.  
  Supported range 0…2147483647.     

- `discord`, `server`, `channel` are optional, if not provided randomly selected available account from [pixverse/account](../api-pixverse-v1/get-pixverse-account) will be used. See [Setup PixVerse](../start-here/setup-pixverse) for details.    
**Note** You may specify the `channel` value alone (omitting `discord` and `server` values) when you wish to use a specific account from the configured list at [pixverse/account](../api-pixverse-v1/get-pixverse-account).

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 10.  
  Currently we **do not recommend** executing more than two `/create_single` jobs at once. The PixVerse bot will most likely throttle you down with a `429`.

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_pixverse-create_single_response %}

{% tab post_pixverse-create_single_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve PixVerse job status and results](../api-pixverse-v1/get-pixverse-jobid). `content` contains message generated by PixVerse reflecting current generation parameters and progress.

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-create_single",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "prompt": "Milla Jovovich riding motorcycle in extreme stormy weather thru California desert",
    "style": "Anime",
    "negative_prompt": "sand",
    "aspect_ratio": "16:9",
    "character": "xiangling",
    "seed_value": 12345, 
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 2,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> We are making videos. We will notify you when it's done. (prompt: Milla Jovovich riding motorcycle in extreme stormy weather thru California desert style: Anime negative-prompt: sand aspect-ratio: 16:9 character: xiangling) Author: <@Discord user id>",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```
{% endtab %}

{% tab post_pixverse-create_single_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "prompt, discord, server or channel value is missing"
      "prompt, negative_prompt, replyRef or replyUrl is too long"
      "style is missing or empty"
      "style <style> not supported, must be one of <list of supported styles>"
      "aspect_ratio <aspect_ratio> not supported, must be one of <list of supported aspect ratios>"
      "character <character> not supported, must be one of <list of supported characters>"
      "seed_value <seed_value> valid range 0-2147483647"
    "code": 400
}
```
{% endtab %}


{% tab post_pixverse-create_single_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_pixverse-create_single_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_pixverse-create_single_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params.

```json
{
    "error": "Apologies! Our AI moderator thinks this prompt or images as potentially violating our [community guidelines](<https://discord.com/channels/1140860020586713128/1168473004498501652>).",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```
{% endtab %}

{% tab post_pixverse-create_single_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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 [pixverse/create_single](#pixverse-create_single-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
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'pixverse-create_single',
  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,
  style: string,
  negative_prompt: string,
  aspect_ratio: string,
  character: string,
  seed_value: number,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by PixVerse reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

{% tabs pixverse-create_single_example %}

{% tab pixverse-create_single_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/pixverse/create_single \
     -F "discord=<Discord token>" \
     -F "server=<Discord server id>" \
     -F "channel=<Discord channel id>" \
     -F "prompt=<PixVerse prompt>" \
     -F 'style="Realistic"'
```
{% endtab %}

{% tab pixverse-create_single_example JavaScript %}
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/pixverse/create_single";
    const token = "API token";
    const prompt = "PixVerse prompt";
    const style = "Realistic";
    const discord = "Discord token";
    const server = "Discord server";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };

    const formData = new FormData();
    formData.append("prompt", prompt);
    formData.append("style", style);
    formData.append("discord", discord);
    formData.append("server", server);
    formData.append("channel", channel);

    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```
{% endtab %}

{% tab pixverse-create_single_example Python %}
``` python
import requests

api_url = "https://api.useapi.net/v1/pixverse/create_single"
token = "API token"
prompt = "PixVerse prompt"
style = "Realistic"
discord = "Discord token"
server = "Discord server"
channel = "Discord channel"

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

files = {
    'prompt': (None, prompt),
    'style': (None, style),
    'discord': (None, discord),
    'server': (None, server),
    'channel': (None, channel)
}

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-meme_face ===
Document URL: https://useapi.net/docs/api-pixverse-v1/post-pixverse-meme_face
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> pixverse/meme_face
parent: PixVerse API v1
nav_order: 800
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## PixVerse [/meme_face](https://pixverse.notion.site/Use-Meme_face-To-Create-Videos-With-The-Face-You-Upload-c6399111aced4b0aa04cb456bc3866d2) command 
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the PixVerse [/meme_face](https://pixverse.notion.site/Use-Meme_face-To-Create-Videos-With-The-Face-You-Upload-c6399111aced4b0aa04cb456bc3866d2) command to your [Discord PixVerse private thread channel](../start-here/setup-pixverse). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [pixverse/jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>](../api-pixverse-v1/get-pixverse-jobid) endpoint.  

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

{: .post }
> **https://api.useapi.net/v1/pixverse/meme_face**

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

##### Request Body
```json
{
    "face": "The face (image jpg/png/jpeg) you want to appear in the meme. File or Blob",
    "prompt": "Prompt",
    "negative_prompt": "What you don't want to in the video",
    "seed_value": "Seed for the generation (0…2147483647)",
    "aspect_ratio": "Aspect-ratio for the video",
    "discord": "Discord token",
    "server": "Discord server id",
    "channel": "Discord channel id",
    "maxJobs": 10,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```
- `face` is **required**, the face (image jpg/png/jpeg) you want to appear in the animated meme. 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.

- `prompt` is **required**, must contain PixVerse [/meme_face](https://pixverse.notion.site/Use-Meme_face-To-Create-Videos-With-The-Face-You-Upload-c6399111aced4b0aa04cb456bc3866d2) prompt.  
  Maximum length 512 characters.  

- `negative_prompt` is optional.  
  Maximum length 512 characters.  

- `seed_value` is optional, seed for the generation.  
  Supported range 0…2147483647.   

- `aspect_ratio` is optional, must be one of following values:  
  `16:9`  
  `9:16`  
  `1:1`  
  `4:3`  
  `3:4`  

- `discord`, `server`, `channel` are optional, if not provided randomly selected available account from [pixverse/account](../api-pixverse-v1/get-pixverse-account) will be used. See [Setup PixVerse](../start-here/setup-pixverse) for details.    
**Note** You may specify the `channel` value alone (omitting `discord` and `server`) when you wish to use a specific account from the configured list at [pixverse/account](../api-pixverse-v1/get-pixverse-account).

- `maxJobs` is optional, if not provided value for `channel` account selected above will be used, if not provided defaulted to 10.  

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_pixverse-meme_face_response %}

{% tab post_pixverse-meme_face_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve PixVerse job status and results](../api-pixverse-v1/get-pixverse-jobid). `content` contains message generated by PixVerse reflecting current generation parameters and progress.

```json
{
    "jobid": "<jobid>",
    "verb": "pixverse-meme_face",
    "status": "started",
    "created": "2023-09-09T02:04:49.667Z",
    "updated": "2023-09-09T02:04:53.490Z",
    "face": { "size": 1628384, "type": "image/png" },
    "prompt": "A girl laughing by the seaside",
    "negative_prompt": "sad face",
    "seed_value": 12345,
    "aspect_ratio": "4:3",
    "discord": "<ABC…secured…xyz>",
    "server": "<Discord server id>",
    "channel": "<Discord channel id>",
    "maxJobs": 10,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "messageId": "<Discord message id>",
    "content": "<@Discord user id> We are making videos. We will notify you when it's done. ([image attached](<https://cdn.discordapp.com/ephemeral-attachments/…>) prompt: A girl laughing by the seaside negative-prompt: sad face aspect-ratio: 4:3) Author: <@Discord user id>)",
    "timestamp": "2023-09-09T02:04:51.926000+00:00",
    "code": 200
}
```
{% endtab %}

{% tab post_pixverse-meme_face_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "face, prompt, discord, server or channel value is missing"
      "prompt, negative_prompt, replyRef or replyUrl is too long"
      "face is not File or Blob"
      "aspect_ratio <aspect_ratio> not supported, must be one of <list of supported aspect ratios>"
      "seed_value <seed_value> valid range 0-2147483647"
    "code": 400
}
```
{% endtab %}


{% tab post_pixverse-meme_face_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_pixverse-meme_face_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_pixverse-meme_face_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params.

```json
{
    "error": "Apologies! Our AI moderator thinks this prompt or images as potentially violating our [community guidelines](<https://discord.com/channels/1140860020586713128/1168473004498501652>).",
    "jobid": "<jobid>",
    "status": "moderated",
    "code": 422
}
```

{% endtab %}

{% tab post_pixverse-meme_face_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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 [pixverse/meme_face](#pixverse-meme_face-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
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  jobid: string, // Use returned jobid value to retrieve job status and results
  verb: 'pixverse-meme_face',
  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
  face: { size: number, type: string },
  prompt: string,
  negative_prompt: string,
  aspect_ratio: string, 
  seed_value: number,
  discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value
  server: string,
  channel: string,
  maxJobs: number,
  replyUrl: string,
  replyRef: string,
  messageId: string,
  content: string, // Contains message generated by PixVerse reflecting current generation parameters and progress
  timestamp: string,
  error: string,
  errorDetails: string,
  executingJobs: string[],
  code: number
}
```

##### Examples

{% tabs pixverse-meme_face_example %}

{% tab pixverse-meme_face_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/pixverse/meme_face \
     -F "discord=<Discord token>" \
     -F "server=<Discord server id>" \
     -F "channel=<Discord channel id>" \
     -F 'face=@"<Path to the face image>"' \
     -F "prompt=<PixVerse prompt>" 
```
{% endtab %}

{% tab pixverse-meme_face_example JavaScript %}
``` javascript
const main = async () => {
    const apiUrl = "https://api.useapi.net/v1/pixverse/meme_face";
    const token = "API token";
    const prompt = "PixVerse prompt";
    const discord = "Discord token";
    const server = "Discord server";
    const channel = "Discord channel";
    const data = {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`
        }
    };
    const formData = new FormData();
    formData.append("prompt", prompt);
    formData.append("discord", discord);
    formData.append("server", server);
    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("face", await responseImage.blob());
    */
    /* 
        // Example 2: Load image from local file (Blob)
        const fsp = require('fs').promises;
        const imageFileName = "./pixverse.png";
        const blob = new Blob([await fsp.readFile(imageFileName)]);
        formData.append("face", blob);
    */
    /*
        // Example 3: Load from input file html element
        // <input id="pixverse-meme_face-image-url" type="file"> 
        const imageFile = document.getElementById(`pixverse-meme_face-image-file`);
        if (imageFile.files[0])
            formData.append("face", imageFile.files[0]);
    */
    data.body = formData;
    const response = await fetch(apiUrl, data);
    const result = await response.json();
    console.log("response", { response, result });
};
main()
```
{% endtab %}

{% tab pixverse-meme_face_example Python %}
``` python
import requests

api_url = "https://api.useapi.net/v1/pixverse/meme_face"
token = "API token"
prompt = "PixVerse prompt"
discord = "Discord token"
server = "Discord server"
channel = "Discord channel"

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

files = {
    'prompt': (None, prompt),
    'discord': (None, discord),
    'server': (None, server),
    '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['face'] = ('image.jpg', image_content, 'image/jpeg')

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

response = requests.post(api_url, headers=headers, files=files)
print(response, response.json())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v1/setup-multiple-pixverse-accounts ===
Document URL: https://useapi.net/docs/api-pixverse-v1/setup-multiple-pixverse-accounts
---
layout: default
title: ⚙️ Setup multiple accounts
parent: PixVerse API v1
nav_order: 5000
---

<span class="required-input-field"><b>This API version is deprecated.</b></span>  
> Please use [PixVerse API v2](../../docs/api-pixverse-v2/) it supports all recent features, including effects, extend, lipsync and more.

## How to use multiple PixVerse accounts 
{: .no_toc }

For your convenience, you can save your PixVerse account(s) configuration, eliminating the need to provide them with every API call. Simply POST your account(s) configuration using the [pixverse/account/`channel`](../api-pixverse-v1/post-pixverse-account-channel) endpoint. 

You may configure as many Discord/PixVerse accounts as desired. If more than one account is configured under [pixverse/account](../api-pixverse-v1/get-pixverse-account), 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 PixVerse account(s) information as outlined at [Setup PixVerse](../start-here/setup-pixverse).
- Post your configuration(s) using the [pixverse/account/`channel`](../api-pixverse-v1/post-pixverse-account-channel) endpoint.
- You can then start making API calls without specifying the `discord`, `server` and `channel` values for every call.

To see all your currently configured PixVerse accounts, please use the [pixverse/account](../api-pixverse-v1/get-pixverse-account) endpoint.

##### Wait there's more…

What if you want to use multiple PixVerse accounts but prefer to implement your own tracking and load balancing logic? Good news – that's still possible! Just continue to provide the `discord`, `server`, `channel`, and `maxJobs` values with each call, and our API will take care of the rest, ensuring proper operation. This is possible because our API 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](../support) if you have any questions or concerns.


=== URL: https://useapi.net/docs/start-here/setup-pixverse ===
Document URL: https://useapi.net/docs/start-here/setup-pixverse
---
layout: default
title: Setup PixVerse
parent: Start Here
nav_order: 400
---
# <img style="height:1.3em;vertical-align: bottom;" src="https://useapi.net/assets/images/pixverse.png"> Setup PixVerse
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 2 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [PixVerse API](../api-pixverse-v2). An active [PixVerse.ai](https://pixverse.ai) account and a [useapi.net subscription](../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`](../api-pixverse-v2/post-pixverse-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful.

## <code class="language-plaintext highlighter-rouge">OPTIONAL</code> 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`](../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="https://useapi.net/assets/images/pixverse_setup_v2-token.png">
</details>

* [POST /accounts/`email`](../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
---
layout: default
title: PixVerse API v2
nav_order: 6000
has_children: true
permalink: /docs/api-pixverse-v2
---

# <img style="height:1.3em;vertical-align: bottom;" src="https://useapi.net/assets/images/pixverse.png"> PixVerse API v2 

<small>December 6, 2024 (April 5, 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](api-pixverse-v2/post-pixverse-videos-create-v4) supports models `v6` (default), `v5.6`, `v5.5`, `v5`, and `v5-fast` with Off-Peak mode (50% off credits). See [model capabilities](api-pixverse-v2/model-capabilities) for feature differences.
* PixVerse [images](api-pixverse-v2/post-pixverse-images-create) supports 7 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), and [Seedream 4.0](https://seed.bytedance.com/en/seedream). 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>

The [web subscription](https://app.pixverse.ai/subscribe) gives you full access to every available video effect with no restrictions, while the official [API subscription](https://platform.pixverse.ai/billing) strictly limits you to just 1, 3 or 5 effect options per billing period. The official API does not support Off-Peak mode (50% off credits).

**v6** — default model for [create](api-pixverse-v2/post-pixverse-videos-create-v4) and [extend](api-pixverse-v2/post-pixverse-videos-extend-v4). All prices include audio. Duration 1-15s at all qualities.

| Video | Credits | [$60/m Premium](https://app.pixverse.ai/subscribe) (15,000 cr) | Per second |
|:------|:-------:|:------:|:------:|
| 1s 360p | 4 | $0.02 | 4 cr/s |
| 10s 360p | 40 | $0.16 | 4 cr/s |
| 15s 360p | 60 | $0.24 | 4 cr/s |
| 1s 540p | 6 | $0.02 | 6 cr/s |
| 10s 540p | 60 | $0.24 | 6 cr/s |
| 15s 540p | 90 | $0.36 | 6 cr/s |
| 1s 720p | 7 | $0.03 | 7 cr/s |
| 10s 720p | 70 | $0.28 | 7 cr/s |
| 15s 720p | 105 | $0.42 | 7 cr/s |
| 1s 1080p | 14 | $0.06 | 14 cr/s |
| 10s 1080p | 140 | $0.56 | 14 cr/s |
| 15s 1080p | 210 | $0.84 | 14 cr/s |

**v5 / v5.5** — used by [modify](api-pixverse-v2/post-pixverse-videos-modify), [lipsync](api-pixverse-v2/post-pixverse-videos-lipsync), [fusion](api-pixverse-v2/post-pixverse-videos-create-fusion), and [transition](api-pixverse-v2/post-pixverse-videos-create-transition). Duration 1-10s (1080p max 8s).

| Video | Credits | [$60/m Premium](https://app.pixverse.ai/subscribe) (15,000 cr) |
|:------|:-------:|:------:|
| 5s 360p | 20 | $0.08 |
| 5s 540p | 30 | $0.12 |
| 5s 720p | 40 | $0.16 |
| 5s 1080p | 80 | $0.32 |
| 10s 360p | 40 | $0.16 |
| 10s 540p | 60 | $0.24 |
| 10s 720p | 80 | $0.32 |
| 8s 1080p | 160 | $0.64 |

**Other**

| Feature | Web | API |
|:--------|:----|:----|
| 5s 4K Upscale          | 30 credits / $0.12   | n/a                 |
| 8s 4K Upscale          | 60 credits / $0.24   | n/a                 |
| Concurrent generations | 8 concurrency limit  | 5 concurrency limit |
| Effect available       | **all** 150+ effects | 3 effect available  |

**Images** — per image, see [images/create](api-pixverse-v2/post-pixverse-images-create) for details

| Model | Credits per image |
|:------|:-----------------:|
| qwen-image (720p / 1080p) | 5 / 10 |
| seedream-4.0, seedream-4.5 | 10 |
| nano-banana, seedream-5.0-lite | 15 |
| nano-banana-2 (512p / 1080p / 1440p / 2160p) | 16 / 25 / 40 / 60 |
| nano-banana-pro (1080p, 1440p / 2160p) | 50 / 90 |

Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include **unlimited image generation** in Relax Mode for select models with generation times ~3s to ~60s based on the model — 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>(April 5, 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="https://useapi.net/assets/images/youtube.svg"> YouTube</a>.  

Blogs:
* [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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: PixVerse API v2
nav_order: 400
---
## Delete PixVerse API account
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v2/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](post-pixverse-accounts-email) request.

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

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

##### Responses 

{% tabs del_account_PixVerse_v2_response %}

{% tab del_account_PixVerse_v2_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_PixVerse_v2_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_PixVerse_v2_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_PixVerse_v2_example %}

{% tab del_account_PixVerse_v2_example 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> 
```
{% endtab %}

{% tab del_account_PixVerse_v2_example 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});
```
{% endtab %}

{% tab del_account_PixVerse_v2_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> images/<code class="language-plaintext highlighter-rouge">image_id</code>
parent: PixVerse API v2
nav_order: 530
---
## Delete an image
{: .no_toc }

<small>March 9, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **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](../start-here/setup-useapi) for details.

##### Path parameter
- `image_id` is **required**. Specify the image_id you want to delete.

##### Responses

{% tabs del_PixVerse_v2_images_image_id_response %}

{% tab del_PixVerse_v2_images_image_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Image was successfully deleted.

{% endtab %}

{% tab del_PixVerse_v2_images_image_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_PixVerse_v2_images_image_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_PixVerse_v2_images_image_id_example %}

{% tab del_PixVerse_v2_images_image_id_example 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"
```
{% endtab %}

{% tab del_PixVerse_v2_images_image_id_example 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});
```
{% endtab %}

{% tab del_PixVerse_v2_images_image_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/<code class="language-plaintext highlighter-rouge">id</code>
parent: PixVerse API v2
nav_order: 1800
---
## Cancel video or image currently being executed by the API
{: .no_toc }

<small>December 6, 2024 (March 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Remove `video_id` or `image_id` generation tracking by the API.

{: .delete }
> **https://api.useapi.net/v2/pixverse/scheduler/`id`**

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

##### Path parameter
- `id` is **required**. Specify `video_id` or `image_id` you want to cancel.

##### Responses 

{% tabs delete_scheduler_PixVerse_v2_scheduler_response %}

{% tab delete_scheduler_PixVerse_v2_scheduler_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>  
{% endtab %}

{% tab delete_scheduler_PixVerse_v2_scheduler_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab delete_scheduler_PixVerse_v2_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_scheduler_PixVerse_v2_scheduler_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
  "error": "Unable to locate running video_id <video_id>"
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs delete_scheduler_PixVerse_v2_scheduler_example %}

{% tab delete_scheduler_PixVerse_v2_scheduler_example 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" 
```
{% endtab %}

{% tab delete_scheduler_PixVerse_v2_scheduler_example 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});
```
{% endtab %}

{% tab delete_scheduler_PixVerse_v2_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> videos/<code class="language-plaintext highlighter-rouge">video_id</code>
parent: PixVerse API v2
nav_order: 800
---
## Delete a video
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `video_id` is **required**. Specify the video_id you want to delete.   

##### Responses 

{% tabs del_PixVerse_v2_videos_video_id_response %}

{% tab del_PixVerse_v2_videos_video_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

Video was successfully deleted.

{% endtab %}

{% tab del_PixVerse_v2_videos_video_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab del_PixVerse_v2_videos_video_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_PixVerse_v2_videos_video_id_example %}

{% tab del_PixVerse_v2_videos_video_id_example 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" 
```
{% endtab %}

{% tab del_PixVerse_v2_videos_video_id_example 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});
```
{% endtab %}

{% tab del_PixVerse_v2_videos_video_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: PixVerse API v2
nav_order: 200
---
## Retrieve PixVerse API account configuration for `email` 
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v2/pixverse/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](post-pixverse-accounts-email) request.

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

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

##### Responses 

{% tabs get_account_PixVerse_v2_account_response %}

{% tab get_account_PixVerse_v2_account_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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"
  }
}
```
{% endtab %}

{% tab get_account_PixVerse_v2_account_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_PixVerse_v2_account_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

Configuration not found. To create configuration use [POST /accounts/`email`](https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email).

{% endtab %}

{% endtabs %}

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

{% tabs get_account_PixVerse_v2_account_example %}

{% tab get_account_PixVerse_v2_account_example Curl %}
``` bash
curl https://api.useapi.net/v2/pixverse/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_PixVerse_v2_account_example 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});
```
{% endtab %}

{% tab get_account_PixVerse_v2_account_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: PixVerse API v2
nav_order: 100
---
## Retrieve PixVerse API accounts configuration
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_PixVerse_v2_response %}

{% tab account_PixVerse_v2_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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…"
    }
}
```
{% endtab %}

{% tab account_PixVerse_v2_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_PixVerse_v2_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST /accounts/`email`](https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email).

{% endtab %}

{% endtabs %}

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

{% tabs account_PixVerse_v2_example %}

{% tab account_PixVerse_v2_example Curl %}
``` bash
curl https://api.useapi.net/v2/pixverse/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_PixVerse_v2_example 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});
```
{% endtab %}

{% tab account_PixVerse_v2_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features
parent: PixVerse API v2
nav_order: 450
---
## Retrieve your PixVerse.ai account information (credits etc)
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve your [PixVerse.ai](https://PixVerse.ai) account information, see [Setup PixVerse](../start-here/setup-pixverse) for details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_features_PixVerse_v2_features_response %}

{% tab get_features_PixVerse_v2_features_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_features_PixVerse_v2_features_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_features_PixVerse_v2_features_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_features_PixVerse_v2_features_example %}

{% tab get_features_PixVerse_v2_features_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/features/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_features_PixVerse_v2_features_example 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});
```
{% endtab %}

{% tab get_features_PixVerse_v2_features_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/<code class="language-plaintext highlighter-rouge">image_id</code>
parent: PixVerse API v2
nav_order: 520
---
## Retrieve a generated image
{: .no_toc }

<small>March 9, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/post-pixverse-images-create).

{: .get }
> **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](../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](../api-pixverse-v2/post-pixverse-images-create)).

##### Responses

{% tabs get_images_image_id_PixVerse_v2_images_image_id_response %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

The image was deleted or not found.

```json
{
    "error": "The original image has been deleted"
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_images_image_id_PixVerse_v2_images_image_id_example %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/images/image_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```
{% endtab %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_example 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});
```
{% endtab %}

{% tab get_images_image_id_PixVerse_v2_images_image_id_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images
parent: PixVerse API v2
nav_order: 510
---
## Retrieve the list of images
{: .no_toc }

<small>December 6, 2024 (March 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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              |

{: .get }
> **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](../start-here/setup-useapi) for details.

##### Query Parameters

- `email` is optional when only one [account](../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

{% tabs get_images_PixVerse_v2_images_response %}

{% tab get_images_PixVerse_v2_images_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab get_images_PixVerse_v2_images_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_images_PixVerse_v2_images_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_images_PixVerse_v2_images_example %}

{% tab get_images_PixVerse_v2_images_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/images/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"
```
{% endtab %}

{% tab get_images_PixVerse_v2_images_example 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});
```
{% endtab %}

{% tab get_images_PixVerse_v2_images_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available
parent: PixVerse API v2
nav_order: 1600
---
## Retrieve the list of videos and images currently running via the API along with the available account capacity
{: .no_toc }

<small>December 6, 2024 (March 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/get-pixverse-videos) or [GET /images](../api-pixverse-v2/get-pixverse-images).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs get_scheduler_available_PixVerse_v2_scheduler_available_response %}

{% tab get_scheduler_available_PixVerse_v2_scheduler_available_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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
        }
    ]
}
```
{% endtab %}

{% tab get_scheduler_available_PixVerse_v2_scheduler_available_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_scheduler_available_PixVerse_v2_scheduler_available_example %}

{% tab get_scheduler_available_PixVerse_v2_scheduler_available_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_scheduler_available_PixVerse_v2_scheduler_available_example 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});
```
{% endtab %}

{% tab get_scheduler_available_PixVerse_v2_scheduler_available_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: PixVerse API v2
nav_order: 1500
---
## Retrieve the list of videos and images currently being executed by the API
{: .no_toc }

<small>December 6, 2024 (March 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/get-pixverse-videos) or [GET /images](../api-pixverse-v2/get-pixverse-images).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs get_scheduler_PixVerse_v2_scheduler_response %}

{% tab get_scheduler_PixVerse_v2_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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>"
    }
]
```
{% endtab %}

{% tab get_scheduler_PixVerse_v2_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
    id: string
    type: 'video' | 'image'
    started: string
    elapsed: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

{% tabs get_scheduler_PixVerse_v2_scheduler_example %}

{% tab get_scheduler_PixVerse_v2_scheduler_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_scheduler_PixVerse_v2_scheduler_example 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});
```
{% endtab %}

{% tab get_scheduler_PixVerse_v2_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/effects
parent: PixVerse API v2
nav_order: 1400
---
## Retrieve the list of effects 
{: .no_toc }

<small>December 6, 2024 (January 8, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

The returned `effect_type` field indicates the number of images required for a given effect:
- `"1"` = single image (e.g., face swap, dance effects)
- `"2"` = two images (e.g., hug, kiss effects)

The total credit cost for a template is `video_base_cost + fixed_cost`.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs get_PixVerse_v2_videos_effects_response %}

{% tab get_PixVerse_v2_videos_effects_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
    "items": [
        {
            "template_id": 380178461924416,
            "display_name": "Miniature Nail Artist Live",
            "workflow_tag": "meta_nanopro_it2v_v5_251204",
            "display_prompt": "Watch your 3D figurine create gorgeous nail designs!",
            "effect_type": "1",
            "template_type": 1,
            "duration": 5,
            "qualities": ["360p", "540p", "720p", "1080p"],
            "video_base_cost": 20,
            "fixed_cost": 20,
            "example_text": "Upload a person photo",
            "thumbnail_path": "https://media.pixverse.ai/…png",
            "thumbnail_video_path": "https://media.pixverse.ai/…mp4",
            "thumbnail_gif_path": "https://media.pixverse.ai/…gif",
            "audio_path": "https://media.pixverse.ai/…mp3",
            "marker": "new"
        },
        {
            "template_id": 326733946317888,
            "display_name": "Hug Together",
            "workflow_tag": "interact_hug_250529",
            "display_prompt": "Create a heartwarming hug moment",
            "effect_type": "2",
            "template_type": 1,
            "duration": 5,
            "qualities": ["360p", "540p", "720p", "1080p"],
            "video_base_cost": 20,
            "fixed_cost": 0,
            "example_text": "Upload a two-person photo",
            "thumbnail_path": "https://media.pixverse.ai/…png",
            "thumbnail_video_path": "https://media.pixverse.ai/…mp4",
            "thumbnail_gif_path": "https://media.pixverse.ai/…gif",
            "audio_path": "https://media.pixverse.ai/…mp3",
            "marker": "hot"
        }
    ],
    "total": 150,
    "next_offset": 0
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_effects_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_effects_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model

```typescript
{   // TypeScript, all fields are optional
  items: {
    template_id: number
    display_name: string
    workflow_tag: string
    display_prompt: string
    effect_type: string       // "1" = single image, "2" = two images required
    template_type: number     // 1 = video template
    duration: number          // video duration in seconds (5 or 8)
    qualities: string[]       // available quality options
    video_base_cost: number   // base credit cost
    fixed_cost: number        // template-specific extra cost (0 for basic, 20 for premium)
    example_text: string      // usage hint (e.g., "Upload a person photo")
    thumbnail_path: string
    thumbnail_video_path: string
    thumbnail_gif_path: string
    audio_path: string
    marker: string            // "new", "hot", or ""
  }[]
  total: number
  next_offset: number
}
```

##### Examples

{% tabs get_PixVerse_v2_videos_effects_example %}

{% tab get_PixVerse_v2_videos_effects_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/effects?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_PixVerse_v2_videos_effects_example 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});
```
{% endtab %}

{% tab get_PixVerse_v2_videos_effects_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/restyles
nav_exclude: true
---
## Retrieve the list of styles used for restyling
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../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 

{% tabs get_PixVerse_v2_videos_restyles_response %}

{% tab get_PixVerse_v2_videos_restyles_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
        }
    ]
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_restyles_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_restyles_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_PixVerse_v2_videos_restyles_example %}

{% tab get_PixVerse_v2_videos_restyles_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/restyles?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_PixVerse_v2_videos_restyles_example 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});
```
{% endtab %}

{% tab get_PixVerse_v2_videos_restyles_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/<code class="language-plaintext highlighter-rouge">video_id</code>
parent: PixVerse API v2
nav_order: 700
---
## Retrieve a generated video or image information
{: .no_toc }

<small>December 6, 2024 (March 9, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/get-pixverse-videos) to retrieve all available videos.

For dedicated image generation and retrieval, see [POST images/create](post-pixverse-images-create) and [GET images/image_id](get-pixverse-images-image_id).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `video_id` is **required**. Specify the video_id or image_id you want to retrieve.   

##### Responses 

{% tabs get_videos_video_id_PixVerse_v2_videos_video_id_response %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

The video was deleted, not found, or is still processing.

```json
{
    "error": "The original video has been deleted"
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_videos_video_id_PixVerse_v2_videos_video_id_example %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/video_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_example 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});
```
{% endtab %}

{% tab get_videos_video_id_PixVerse_v2_videos_video_id_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/voices
parent: PixVerse API v2
nav_order: 1300
---
## Retrieve the list of voices for lipsync
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  


##### Responses 

{% tabs get_PixVerse_v2_videos_voices_response %}

{% tab get_PixVerse_v2_videos_voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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"
        }
    ]
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_voices_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_PixVerse_v2_videos_voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    tts_list: {
        speaker_id: string
        url: string
        display_name: string
    }[]
}
```

##### Examples

{% tabs get_PixVerse_v2_videos_voices_example %}

{% tab get_PixVerse_v2_videos_voices_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/voices/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_PixVerse_v2_videos_voices_example 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});
```
{% endtab %}

{% tab get_PixVerse_v2_videos_voices_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos ===
Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos
parent: PixVerse API v2
nav_order: 600
---
## Retrieve the list of videos 
{: .no_toc }

<small>December 6, 2024 (July 8, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters

- `email` is optional when only one [account](../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 

{% tabs get_videos_PixVerse_v2_videos_response %}

{% tab get_videos_PixVerse_v2_videos_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_videos_PixVerse_v2_videos_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_videos_PixVerse_v2_videos_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_videos_PixVerse_v2_videos_example %}

{% tab get_videos_PixVerse_v2_videos_example Curl %}
``` bash
curl "https://api.useapi.net/v2/pixverse/videos/?email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_videos_PixVerse_v2_videos_example 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});
```
{% endtab %}

{% tab get_videos_PixVerse_v2_videos_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities ===
Document URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities
---
layout: default
title: Model Capabilities
parent: PixVerse API v2
nav_order: 50
---

<small>December 5, 2025 (April 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

## Video Models
{: .no_toc }

### Available Video Models

| Model | Description |
|-------|-------------|
| **v6** | Latest model with audio, multi-shot, up to 15s at all qualities |
| **v5.6** | Audio generation |
| **v5.5** | Audio generation |
| **v5** | Lip sync TTS, sound effects |
| **v5-fast** | Fast generation, no audio features |

### Quality & Duration Matrix

**v6** supports duration **1-15 seconds** at all qualities including 1080p.

Pre-v6 models support duration **1-10 seconds**, except:
- **1080p** is limited to **1-8 seconds** maximum
- **create-frames** endpoint is limited to **1-8 seconds**

| Quality | v6 Duration | v5.x Duration | Notes |
|---------|-------------|---------------|-------|
| **360p** | 1-15s | 1-10s | All tiers |
| **540p** | 1-15s | 1-10s | All tiers |
| **720p** *(v6 default)* | 1-15s | 1-10s | Standard+ |
| **1080p** | 1-15s | 1-8s | Pro/Premium |

### Audio Features by Model

| Model | Audio Feature | Usage |
|-------|---------------|-------|
| **v6** | Integrated audio + multi-shot | `audio: true`, `multi_shot: true` |
| **v5.6** | Integrated audio | `audio: true` |
| **v5.5** | Integrated audio | `audio: true` |
| **v5** | Lip sync + Sound effects | `lip_sync_tts_prompt` + `sound_effect_prompt` |
| **v5-fast** | None | No audio support |

### v6 Audio and Multi-Shot

Model `v6` features **integrated audio generation** and **multi-shot storytelling** — the AI generates videos with multiple camera angles and scene cuts, with voice, lip sync, and background music generated together in a single step.

```json
{
  "model": "v6",
  "audio": true,
  "multi_shot": true,
  "prompt": "A detective says 'Follow the clues' then cut to a suspect running through an alley"
}
```

### v5.5/v5.6 Native Audio

Models `v5.5` and `v5.6` feature **integrated audio generation** - voice, lip sync, and background music are generated together with the video in a single step.

```json
{
  "model": "v5.6",
  "audio": true,
  "prompt": "A woman says hello and waves at the camera"
}
```

| v5.5/v5.6/v6 Audio | v5 Audio |
|---------------------|----------|
| Use `audio: true` | Use `lip_sync_tts_prompt` + `sound_effect_prompt` |
| Voice integrated with video | Separate lipsync step available |
| Background music auto-generated | Manual via `sound_effect_prompt` |
| Lipsync endpoint not supported | Lipsync endpoint supported |

### Feature Comparison

| Feature | v6 | v5.6 | v5.5 | v5 | v5-fast |
|---------|-----|------|------|----|---------|
| Native Audio | yes | yes | yes | - | - |
| Multi-Shot | yes | - | - | - | - |
| Lip Sync TTS | - | - | - | yes | - |
| Sound Effects | - | - | - | yes | - |
| Duration 1-15s | yes | - | - | - | - |
| Duration 1-10s | yes | yes | yes | yes | yes |
| Preview Mode | yes | yes | yes | yes | yes |

### Video Endpoint Compatibility

| Endpoint | v6 | v5.6 | v5.5 | v5 | v5-fast |
|----------|-----|------|------|----|---------|
| [POST videos/create](post-pixverse-videos-create-v4) | yes | yes | yes | yes | yes |
| [POST videos/create-frames](post-pixverse-videos-create-frames-v4) | - | yes | yes | yes | yes |
| [POST videos/create-transition](post-pixverse-videos-create-transition)<br/>(2-frame) | - | yes | yes | yes | - |
| [POST videos/create-transition](post-pixverse-videos-create-transition)<br/>(3+ frame) | - | - | - | yes | - |
| [POST videos/extend](post-pixverse-videos-extend-v4) | yes | - | yes | yes | - |
| [POST videos/modify](post-pixverse-videos-modify) | - | - | yes | - | - |
| [POST videos/upscale](post-pixverse-videos-upscale) | yes | yes | yes | yes | yes |
| [POST videos/lipsync](post-pixverse-videos-lipsync) | - | - | - | yes | - |
| [POST videos/create-fusion](post-pixverse-videos-create-fusion) | - | - | - | yes | - |

### Video Endpoint Constraints

| Endpoint | Supported Models | Max Duration | Max Quality |
|----------|------------------|--------------|-------------|
| create | v6, v5.6, v5.5, v5, v5-fast | 15s (v6), 10s/8s@1080p (v5.x) | 1080p |
| create-frames | v5.6, v5.5, v5, v5-fast | 8s | 1080p |
| create-transition<br/>(2-frame) | v5.6, v5.5, v5 | 8s | 1080p |
| create-transition<br/>(3+ frame) | v5 only | 8s | 1080p |
| extend | v6, v5.5, v5 | 15s (v6), 10s/8s@1080p (v5.x) | 1080p |
| modify | v5.5 only | source video | 720p |
| lipsync | v5 only | source video | source |
| fusion | v5 only | 10s (8s@1080p) | 1080p |

### Quality Tier Requirements

- **360p**: All subscription tiers
- **540p**: All subscription tiers
- **720p**: Standard or higher (v6 default)
- **1080p**: Pro/Premium

---

## Image Models
{: .no_toc }

### Available Image Models

| Model | Qualities | Max Refs | Est. Time | Default |
|-------|-----------|:--------:|:---------:|:-------:|
| **qwen-image** | 720p, 1080p | 3 | ~3s | **default** |
| **nano-banana** | 1080p | 3 | ~10s | |
| **seedream-4.0** | 1080p, 1440p, 2160p | 6 | ~10s | |
| **seedream-4.5** | 1440p, 2160p | 6 | ~15s | |
| **nano-banana-2** | 512p, 1080p, 1440p, 2160p | 9 | ~30s | |
| **seedream-5.0-lite** | 1440p, 1800p | 6 | ~30s | |
| **nano-banana-pro** | 1080p, 1440p, 2160p | 9 | ~60s | |

### Image Aspect Ratios

All image models support: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9`.

All models except `qwen-image` also support `auto` (default). `qwen-image` defaults to `1:1`.

### Image Endpoints

All image models are supported by the following endpoints:

| Endpoint |
|----------|
| [GET images](get-pixverse-images) |
| [POST images/create](post-pixverse-images-create) |
| [GET images/image_id](get-pixverse-images-image_id) |
| [DEL images/image_id](del-pixverse-images-image_id) |

### Unlimited Image Generation (Relax Mode)

Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models with generation times ~3s to ~60s based on the model. The number of models with unlimited access increases with higher tiers:

| Plan | Price | Unlimited Models |
|------|:-----:|:-----------------|
| Pro | $30/m | qwen-image |
| Premium | $60/m | qwen-image + selectively others |
| Ultra | $199/m | ALL 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: PixVerse API v2
nav_order: 300
---
## Create or update PixVerse API account configuration
{: .no_toc }

<small>December 6, 2024 (March 11, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---
See [Setup PixVerse](../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.

{: .post }
> **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](../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](../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](../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 

{% tabs post_account_PixVerse_v2_response %}

{% tab post_account_PixVerse_v2_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a> 

```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"
  }
}
```

{% endtab %}

{% tab post_account_PixVerse_v2_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_account_PixVerse_v2_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "<Error message>",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_account_PixVerse_v2_example %}

{% tab post_account_PixVerse_v2_example 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": …}'
```
{% endtab %}

{% tab post_account_PixVerse_v2_example 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});
```
{% endtab %}

{% tab post_account_PixVerse_v2_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files ===
Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files
parent: PixVerse API v2
nav_order: 500
---
## Upload image, video or audio file
{: .no_toc }

<small>December 6, 2024 (April 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](../api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs post_files_PixVerse_v2_files_response %}

{% tab post_files_PixVerse_v2_files_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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>"
}
```

{% endtab %}

{% tab post_files_PixVerse_v2_files_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_files_PixVerse_v2_files_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_files_PixVerse_v2_files_example %}

{% tab post_files_PixVerse_v2_files_example 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
```
{% endtab %}

{% tab post_files_PixVerse_v2_files_example 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});
```
{% endtab %}

{% tab post_files_PixVerse_v2_files_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create
parent: PixVerse API v2
nav_order: 540
---
## Create an image using a text prompt
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

<small>March 9, 2026</small>

1. TOC
{:toc}

---

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](../api-pixverse-v2/post-pixverse-files).

##### Model Comparison Matrix

| Model | Qualities | Aspect Ratios | Ref Images | Est. Time |
|:------|:----------|:--------------|:-----------|:---------|
| qwen-image *(default)* | 720p, 1080p | 1:1 (default), all except auto | 1-3 via `image_path_1`…`3` | ~3s |
| nano-banana | 1080p | auto (default), all | 1-3 via `image_path_1`…`3` | ~10s |
| seedream-4.0 | 1080p, 1440p, 2160p | auto (default), all | 1-6 via `image_path_1`…`6` | ~10s |
| seedream-4.5 | 1440p, 2160p | auto (default), all | 1-6 via `image_path_1`…`6` | ~15s |
| nano-banana-2 | 512p, 1080p, 1440p, 2160p | auto (default), all | 1-9 via `image_path_1`…`9` | ~30s |
| seedream-5.0-lite | 1440p, 1800p | auto (default), all | 1-6 via `image_path_1`…`6` | ~30s |
| nano-banana-pro | 1080p, 1440p, 2160p | auto (default), all | 1-9 via `image_path_1`…`9` | ~60s |

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

**Unlimited Image Generation (Relax Mode)**: Pro ($30/m) and higher [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models with generation times ~3s to ~60s based on the model. The number of models with unlimited access increases with higher tiers — Ultra ($199/m) includes ALL image models unlimited.

</details>

To retrieve generated image(s), use:
* [GET images/`imageId`](https://useapi.net/docs/api-pixverse-v2/get-pixverse-images-image_id)

To delete a generated image, use:
* [DEL images/`imageId`](https://useapi.net/docs/api-pixverse-v2/del-pixverse-images-image_id)

{: .post }
> **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](../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",
    "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](../api-pixverse-v2/get-pixverse-accounts).

- `prompt` is **required**, describe your image.
  Maximum length 5,000 characters.

- `model` is optional.
  Supported values:
  * `qwen-image` (default) - Affordable price, balanced performance (~3s). Does not support `auto` aspect ratio. Up to 3 reference images.
  * `nano-banana` - High visual quality, excellent character editing (~10s). Up to 3 reference images.
  * `nano-banana-2` - Fastest image generation model from Google (~30s). Up to 9 reference images.
  * `nano-banana-pro` - State-of-the-art image generation and editing model (~60s). Up to 9 reference images.
  * `seedream-4.0` - Fast 2K generation, excellent text editing (~10s). Up to 6 reference images.
  * `seedream-4.5` - Enhanced consistency and prompt adherence (~15s). Up to 6 reference images.
  * `seedream-5.0-lite` - Best image model with Web Search from ByteDance (~30s). Up to 6 reference images.

- `quality` is optional, model-specific. Defaults to the model's first quality.
  * `qwen-image`: `720p` (default), `1080p`.
  * `nano-banana`: `1080p` only.
  * `nano-banana-2`: `512p` (default), `1080p`, `1440p`, `2160p`.
  * `nano-banana-pro`: `1080p` (default), `1440p`, `2160p`.
  * `seedream-4.0`: `1080p` (default), `1440p`, `2160p`.
  * `seedream-4.5`: `1440p` (default), `2160p`.
  * `seedream-5.0-lite`: `1440p` (default), `1800p`.

- `aspect_ratio` is optional.
  Supported values: `auto` (default), `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9`.
  **Note:** `qwen-image` does not support `auto` — defaults to `1:1`.

- `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](../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)).
  Nano Banana, Nano Banana 2, and Nano Banana Pro models have less content moderation and are capable of using photos of minors or famous people as reference images. Use responsibly and in compliance with applicable laws and regulations.

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

- `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](../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

{% tabs post_PixVerse_v2_images_create_response %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `image_id` or values from `success_ids` array to retrieve image status and results using [GET images/`imageId`](../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
}
```

{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_images_create_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_PixVerse_v2_images_create_example %}

{% tab post_PixVerse_v2_images_create_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_images_create_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_images_create_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-frames
parent: PixVerse API v2
nav_order: 860
---
## Create video using first and last frames
{: .no_toc }

<small>March 31, 2025 (January 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint uses PixVerse models `v5.6`, `v5.5`, `v5`, and `v5-fast`. Default: `v5.5`.

To upload prompt image use [POST /files](../api-pixverse-v2/post-pixverse-files).

{: .post }
> **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](../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](../api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional.
  Supported values: `v5.6`, `v5.5`, `v5`, and `v5-fast`. Default: `v5.6`. See [Model Capabilities](model-capabilities) for feature differences.

- `prompt` is optional, describe your video.  
  Maximum length 2048 characters.

- `first_frame_path` is **required**, provide path of uploaded image via [POST /files](../api-pixverse-v2/post-pixverse-files).

- `last_frame_path` is **required**, provide path of uploaded image via [POST /files](../api-pixverse-v2/post-pixverse-files).

- `duration` is optional. Video duration in seconds.
  Supported values: `1` through `8`. Default: `5`.

- `quality` is optional. Video quality.
  Supported values: `1080p`, `720p`, `540p` (default), `360p`.

- `audio` is optional (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. See [Model Capabilities](model-capabilities#v55v56-native-audio).
  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](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](../api-pixverse-v2/get-pixverse-videos-voices).

- `seed` is optional.   
  Valid range 1…2147483647. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_create-frames-v4_response %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_create-frames-v4_example %}

{% tab post_PixVerse_v2_videos_create-frames-v4_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-frames-v4_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-fusion
parent: PixVerse API v2
nav_order: 890
---

## Create video using image fusion

{: .no_toc }

<small>May 16, 2025 (January 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Upload up to three frames and describe the content you want to create.

This endpoint uses PixVerse model `v5` only. See [Model Capabilities](model-capabilities) for details.

To upload prompt images use [POST /files](../api-pixverse-v2/post-pixverse-files).

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "prompt": "A dog @pic1 and a cat @pic2 traveling together in the car @pic3",
    "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": "540p",
    "aspect_ratio": "16:9",
    "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](../api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional.
  Supported value: `v5`.

- `prompt` is **required**, describe your video.  
  Maximum length 2048 characters.  
  Use special notation "@pic1" to reference the frame_1_path image, "@pic2" to reference the frame_2_path image and "@pic3" to reference the frame_3_path image.

- `frame_1_path` is **required**, provide the path of uploaded image via [POST /files](../api-pixverse-v2/post-pixverse-files).  
  This image will be referenced in the prompt as "@pic1".

- `frame_2_path` is optional, provide the path of the uploaded image via [POST /files](../api-pixverse-v2/post-pixverse-files).  
  If provided, this image will be referenced in the prompt as "@pic2".

- `frame_3_path` is optional, provide the path of the uploaded image via [POST /files](../api-pixverse-v2/post-pixverse-files).  
  If provided, this image will be referenced in the prompt as "@pic3".

- `duration` is optional. Video duration in seconds.
  Supported values: `1` through `10`. Default: `5`. Note: 1080p quality is limited to 8 seconds maximum.

- `quality` is optional. Video quality.  
  Supported values: `1080p`, `720p`, `540p` (default), `360p` (Turbo).

- `aspect_ratio` is optional. Default is `16:9`.  
  Supported values:  `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`

- `seed` is optional.   
  Valid range 1…999999. 

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_create-fusion_response %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_create-fusion_example %}

{% tab post_PixVerse_v2_videos_create-fusion_example 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 @pic1 and a cat @pic2 traveling together", "frame_1_path": "…", "frame_2_path": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_example JavaScript %}
``` javascript
const prompt = "A dog @pic1 and a cat @pic2 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-fusion_example Python %}
``` python
import requests
prompt = "A dog @pic1 and a cat @pic2 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-transition
parent: PixVerse API v2  
nav_order: 890
---
## Create transition video
{: .no_toc }

<small>August 29, 2025 (January 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/post-pixverse-files).

{: .post }
> **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](../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](../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](model-capabilities) for feature differences.

- `quality` is optional. Video quality.
  Supported values: `1080p`, `720p`, `540p` (default), `360p`.

- `seed` is optional.   
  Valid range 1…2147483647. 

- `frame_1_path` is **required**, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_2_path` is **required**, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_3_path` is optional, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_4_path` is optional, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_5_path` is optional, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_6_path` is optional, provide path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `frame_7_path` is optional, provide path of uploaded image via [POST files](../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](model-capabilities#v55v56-native-audio).
  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](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](../api-pixverse-v2/get-pixverse-videos-voices).

- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.    

- `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](../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 

{% tabs post_PixVerse_v2_videos_create-transition_response %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_create-transition_example %}

{% tab post_PixVerse_v2_videos_create-transition_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-transition_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create
parent: PixVerse API v2
nav_order: 850
---
## Create video or image
{: .no_toc }

<small>March 24, 2025 (April 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint uses PixVerse models `v6`, `v5.6`, `v5.5`, `v5`, and `v5-fast`. Default: `v6`. See [Model Capabilities](model-capabilities) for feature differences.

For dedicated image generation, see [POST images/create](post-pixverse-images-create).

To upload prompt image use [POST files](../api-pixverse-v2/post-pixverse-files).

{: .post }
> **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](../start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "email": "Optional PixVerse API account email",
    "model": "v6",
    "prompt": "Required text prompt",
    "first_frame_path": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png",
    "duration": 5,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "audio": true,
    "seed": 654321,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
```

**Note:** When using `template_id` for effects, the model is determined by the template itself. Do not specify `model` parameter with templates.

- `email` is optional, if not specified API will randomly select account from available [accounts](../api-pixverse-v2/get-pixverse-accounts).  

- `model` is optional.
  Supported values: `v6` (default), `v5.6`, `v5.5`, `v5`, `v5-fast`. See [Model Capabilities](model-capabilities) for feature differences.

- `prompt` is optional, describe your video.  
  Maximum length 2048 characters.
  
- `first_frame_path` is optional, provide the path of uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files).

- `last_frame_path` is optional, provide the path of the uploaded image via [POST files](../api-pixverse-v2/post-pixverse-files). Some effects require two images (e.g., "Forever Us"). Check the template field `effect_type` for the number of required images, and if it is set to `2` you will need to provide a `last_frame_path` image.

- `template_id` is optional, provide template_id of desired effect, see [GET videos/effects](../api-pixverse-v2/get-pixverse-videos-effects).

- `duration` is optional. Video 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`.

- `aspect_ratio` is optional.
  Supported values:  `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`

- `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](../api-pixverse-v2/get-pixverse-videos-voices).

- `audio` is optional. **v5.5, v5.6, and v6.** Set to `true` to enable integrated audio generation (voice, lip sync, and background music generated together with the video). This replaces the separate `lip_sync_tts_prompt` and `sound_effect_prompt` parameters used in v5 model.
  Supported values: `false` (default), `true`.

- `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. Set to `true` to generate a fast preview at lower quality. Use [POST videos/upscale](post-pixverse-videos-upscale) to upscale the preview to full quality.
  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 with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.    

- `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](../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 

{% tabs post_PixVerse_v2_videos_create-v4_response %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` or `image_id` to retrieve video status and results using [GET videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_PixVerse_v2_videos_create-v4_example %}

{% tab post_PixVerse_v2_videos_create-v4_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_create-v4_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend
parent: PixVerse API v2
nav_order: 870
---
## Extend video 
{: .no_toc }

<small>March 31, 2025 (April 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](../api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to extend.

{: .post }
> **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](../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](../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 2048 characters.
  
- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](../api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](../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 with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_extend-v4_response %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_extend-v4_example %}

{% tab post_PixVerse_v2_videos_extend-v4_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_extend-v4_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/lipsync
parent: PixVerse API v2
nav_order: 1100
---
## Lip sync video
{: .no_toc }

<small>December 6, 2024 (January 27, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

* This endpoint uses PixVerse model `v5` only. See [Model Capabilities](model-capabilities) for details.

* Lip sync a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](../api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](../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](../api-pixverse-v2/post-pixverse-files) and use `path` to specify the audio you want to use for lip sync.

{: .post }
> **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](../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](../api-pixverse-v2/get-pixverse-accounts).  

- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](../api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](../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](../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](../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 with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_lipsync_response %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_lipsync_example %}

{% tab post_PixVerse_v2_videos_lipsync_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_lipsync_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/modify
parent: PixVerse API v2
nav_order: 875
---
## Modify video
{: .no_toc }

<small>January 26, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](../api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to modify.

{: .post }
> **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](../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](../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 2048 characters.

- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](../api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](../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 with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.

- `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](../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

{% tabs post_PixVerse_v2_videos_modify_response %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

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"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_modify_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_modify_example %}

{% tab post_PixVerse_v2_videos_modify_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_modify_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_modify_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/restyle
nav_exclude: true
---
## Restyle video 
{: .no_toc }

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


## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

> [v5 release endpoint changes](../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](../api-pixverse-v2/get-pixverse-videos).

* Upload the video using [POST /files](../api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to restyle.

{: .post }
> **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](../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](../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 2048 characters.
  
- `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](../api-pixverse-v2/get-pixverse-videos).

- `video_path` is optional, upload the video using [POST /files](../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](../api-pixverse-v2/get-pixverse-videos-restyles). 

- `seed` is optional.   
  Valid range 1…2147483647. 
 
- `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods with up to 50% credit savings. Results are usually delivered within 24 hours. Off-Peak Mode generations are not tracked by the scheduler and are not counted towards the number of currently executed jobs. The replyUrl webhook will also be ignored. You must use [GET videos](../api-pixverse-v2/get-pixverse-videos) to retrieve the generated 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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_restyle-v4_response %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message.

```json
{
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_restyle-v4_example %}

{% tab post_PixVerse_v2_videos_restyle-v4_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_restyle-v4_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale
parent: PixVerse API v2
nav_order: 1200
---
## Upscale to 4K
{: .no_toc }

<small>December 6, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .post }
> **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](../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](../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.  

- `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](../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 

{% tabs post_PixVerse_v2_videos_upscale_response %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use the returned `video_id` to retrieve video status and results using [GET /videos](../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>"
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized"
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

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."
}
```
{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span> 

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](../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."
}
```

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_PixVerse_v2_videos_upscale_example %}

{% tab post_PixVerse_v2_videos_upscale_example 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": "…"}'
```
{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_example 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});
```
{% endtab %}

{% tab post_PixVerse_v2_videos_upscale_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/start-here/setup-runwayml ===
Document URL: https://useapi.net/docs/start-here/setup-runwayml
---
layout: default
title: Setup Runway
parent: Start Here
nav_order: 300
---
# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/runwayml.svg"> Setup Runway
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 2 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [Runway API](../api-runwayml-v1). A [Runway](https://runwayml.com) account and a [useapi.net subscription](../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](../api-runwayml-v1/get-runwayml-text_to_image_preview) generations
* Unlimited number of [Image Upscaler](../api-runwayml-v1/get-runwayml-image_upscaler) generations
* Unlimited number of [Transcribe](../api-runwayml-v1/get-runwayml-transcribe) generations
* Unlimited number of [Super-Slow Motion](../api-runwayml-v1/post-runwayml-super_slow_motion) generations
* Unlimited number of [Frames Describe](../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`](../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
---
layout: default
title: Runway API v1
nav_order: 5000
has_children: true
permalink: /docs/api-runwayml-v1
---

# <img style="height:1em;vertical-align: middle;" src="https://useapi.net/assets/images/runwayml.svg"> Runway API v1 
<small>August 8, 2024 (March 5, 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 12 models: [Gen-4.5, Gen-4, Gen-4 Turbo](https://runwayml.com), [Kling 3.0 Pro/Standard](https://klingai.com), [Kling 2.6 Pro/I2V](https://klingai.com), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2/Pro](https://openai.com/index/sora/), [Wan 2.6 Flash](https://wan.video/), and [Wan 2.2 Animate](https://github.com/Wan-Video/Wan2.2) with text-to-video, image-to-video, and multi-shot 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 [Images](../../docs/api-runwayml-v1/post-runwayml-images-create) is a unified image generation endpoint supporting [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), [Seedream 5](https://www.volcengine.com/product/seedream), Gen-4, and Gen-4 Turbo models 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>(March 5, 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:
* [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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Runway API v1
nav_order: 400
---
## Delete Runway API account
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/runwayml/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](post-runwayml-accounts-email) request.

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

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

##### Responses 

{% tabs del_account_Runwayml_response %}

{% tab del_account_Runwayml_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_Runwayml_example %}

{% tab del_account_Runwayml_example 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> 
```
{% endtab %}

{% tab del_account_Runwayml_example 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});
```
{% endtab %}

{% tab del_account_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> assets/<code class="language-plaintext highlighter-rouge">assetId</code>
parent: Runway API v1
nav_order: 1700
---
## Delete asset 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).

{: .delete }
> **https://api.useapi.net/v1/runwayml/assets/`assetId`**

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

##### Path parameter
- `assetId` is **required**. Specify assetId you want to delete.

##### Responses 

{% tabs delete_assets_Runwayml_assets_response %}

{% tab delete_assets_Runwayml_assets_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```json
{
  "success": true
}
```
{% endtab %}

{% tab delete_assets_Runwayml_assets_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab delete_assets_Runwayml_assets_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_assets_Runwayml_assets_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
  "error": "Not found."
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs delete_assets_Runwayml_assets_example %}

{% tab delete_assets_Runwayml_assets_example 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" 
```
{% endtab %}

{% tab delete_assets_Runwayml_assets_example 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});
```
{% endtab %}

{% tab delete_assets_Runwayml_assets_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/<code class="language-plaintext highlighter-rouge">taskId</code>
parent: Runway API v1
nav_order: 1800
---
## Cancel task currently being executed by the API
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/runwayml/scheduler/`taskId`**

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

##### Path parameter
- `taskId` is **required**. Specify taskId you want to cancel.

##### Responses 

{% tabs delete_scheduler_Runwayml_scheduler_response %}

{% tab delete_scheduler_Runwayml_scheduler_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>  
{% endtab %}

{% tab delete_scheduler_Runwayml_scheduler_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab delete_scheduler_Runwayml_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_scheduler_Runwayml_scheduler_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
  "error": "Unable to locate running taskId <taskId>"
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs delete_scheduler_Runwayml_scheduler_example %}

{% tab delete_scheduler_Runwayml_scheduler_example 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" 
```
{% endtab %}

{% tab delete_scheduler_Runwayml_scheduler_example 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});
```
{% endtab %}

{% tab delete_scheduler_Runwayml_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> tasks/<code class="language-plaintext highlighter-rouge">taskId</code>
parent: Runway API v1
nav_order: 2100
---
## Delete task 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v1/runwayml/tasks/`taskId`**

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

##### Path parameter
- `taskId` is **required**. Specify taskId you want to delete.

##### Responses 

{% tabs delete_tasks_Runwayml_tasks_response %}

{% tab delete_tasks_Runwayml_tasks_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```json
{
  "success": true
}
```
{% endtab %}

{% tab delete_tasks_Runwayml_tasks_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab delete_tasks_Runwayml_tasks_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_tasks_Runwayml_tasks_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
  "error": "Not found."
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs delete_tasks_Runwayml_tasks_example %}

{% tab delete_tasks_Runwayml_tasks_example 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" 
```
{% endtab %}

{% tab delete_tasks_Runwayml_tasks_example 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});
```
{% endtab %}

{% tab delete_tasks_Runwayml_tasks_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Runway API v1
nav_order: 200
---
## Retrieve Runway API account configuration for `email` 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v1/runwayml/accounts/`email`**

The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](post-runwayml-accounts-email) request.

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

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

##### Responses 

{% tabs get_account_Runwayml_email_response %}

{% tab get_account_Runwayml_email_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a>
```json
{
  "email": "user-1@example.com",
  "password": "<password>",
  "maxJobs": 5,
  "jwt": {
    "token": "<token>",
    "exp": 1734858598.864,
    "iat": 1732266598.864,
    "id": 123456,
  }        
}
```
{% endtab %}

{% tab get_account_Runwayml_email_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_Runwayml_email_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

Configuration not found. To create configuration use [POST /accounts/`email`](https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email).

{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  email: string,
  password: string,
  maxJobs: number,
  jwt: {
    token: string,
    exp: number,
    iat: number,
    id: number,
  }
}
```

##### Examples

{% tabs get_account_Runwayml_email_example %}

{% tab get_account_Runwayml_email_example Curl %}
``` bash
curl https://api.useapi.net/v1/runwayml/accounts/<email> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_Runwayml_email_example 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});
```
{% endtab %}

{% tab get_account_Runwayml_email_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: Runway API v1
nav_order: 100
---
## Retrieve Runway API accounts configuration
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs account_Runway_response %}

{% tab account_Runway_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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,
    }
}
```
{% endtab %}

{% tab account_Runway_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_Runway_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST /accounts/`email`](https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email).

{% endtab %}

{% endtabs %}

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

{% tabs account_Runway_example %}

{% tab account_Runway_example Curl %}
``` bash
curl https://api.useapi.net/v1/runwayml/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_Runway_example 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});
```
{% endtab %}

{% tab account_Runway_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/<code class="language-plaintext highlighter-rouge">assetId</code>
parent: Runway API v1
nav_order: 1400
---
## Retrieve assets 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `assetId` is **required**. Specify the assetId you want to retrieve. 

##### Responses 

{% tabs get_assets_assetId_Runwayml_assets_assetId_response %}

{% tab get_assets_assetId_Runwayml_assets_assetId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```

{% endtab %}

{% tab get_assets_assetId_Runwayml_assets_assetId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_assets_assetId_Runwayml_assets_assetId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_assets_assetId_Runwayml_assets_assetId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_assets_assetId_Runwayml_assets_assetId_example %}

{% tab get_assets_assetId_Runwayml_assets_assetId_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/assets/assetId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_assets_assetId_Runwayml_assets_assetId_example 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});
```
{% endtab %}

{% tab get_assets_assetId_Runwayml_assets_assetId_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets
parent: Runway API v1
nav_order: 1300
---
## Retrieve assets 
{: .no_toc }

<small>August 8, 2024 (August 4, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Runway [Assets](https://app.runwayml.com/video-tools/assets).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](../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 

{% tabs get_assets_Runwayml_assets_response %}

{% tab get_assets_Runwayml_assets_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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,
    }
]
```

{% endtab %}

{% tab get_assets_Runwayml_assets_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_assets_Runwayml_assets_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_assets_Runwayml_assets_example %}

{% tab get_assets_Runwayml_assets_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_assets_Runwayml_assets_example 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});
```
{% endtab %}

{% tab get_assets_Runwayml_assets_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features
parent: Runway API v1
nav_order: 402
---
## Retrieve the Runway account features
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve account credits information and other details.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](../api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes required.
  
##### Responses 

{% tabs get_features_Runwayml_features_response %}

{% tab get_features_Runwayml_features_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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
    }
}
```

{% endtab %}

{% tab get_features_Runwayml_features_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_features_Runwayml_features_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_features_Runwayml_features_example %}

{% tab get_features_Runwayml_features_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/features/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_features_Runwayml_features_example 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});
```
{% endtab %}

{% tab get_features_Runwayml_features_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> frames/describe
parent: Runway API v1
nav_order: 870
---
## Get image description 
{: .no_toc }

<small>February 24, 2025 (April 28, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Extract a text image description that can be adjusted and used as a starting point for the prompt in [POST frames/create](../api-runwayml-v1/post-runwayml-frames-create).

This endpoint is available for all Runway accounts, including free ones.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `image_assetId` is **required**. Specify the image asset. You can upload an image via [POST assets](../api-runwayml-v1/post-runwayml-assets), you can get a list of all image assets via [GET assets](../api-runwayml-v1/get-runwayml-assets).

##### Responses 

{% tabs get_Runwayml_frames_describe_response %}

{% tab get_Runwayml_frames_describe_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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."
}
```

{% endtab %}

{% tab get_Runwayml_frames_describe_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_Runwayml_frames_describe_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs get_Runwayml_frames_describe_example %}

{% tab get_Runwayml_frames_describe_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/frames/describe/image_assetId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_Runwayml_frames_describe_example 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});
```
{% endtab %}

{% tab get_Runwayml_frames_describe_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> image_upscaler
parent: Runway API v1
nav_order: 1100
---
## Upscale or Downscale image to specified dimensions
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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. 

{: .get }
> **https://api.useapi.net/v1/runwayml/image_upscaler/?…**

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

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

##### Query Parameters
- `email` is optional when only one [account](../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](../api-runwayml-v1/get-runwayml-text_to_image_preview) or an asset URL from [GET /assets](../api-runwayml-v1/get-runwayml-assets). You may need to upload the image using [POST /assets](../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 

{% tabs get_image_upscaler_Runwayml_image_upscaler_response %}

{% tab get_image_upscaler_Runwayml_image_upscaler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

Binary response containing a new image.

{% endtab %}

{% tab get_image_upscaler_Runwayml_image_upscaler_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_image_upscaler_Runwayml_image_upscaler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_image_upscaler_Runwayml_image_upscaler_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  
```json
{
    "message": "Image was not found"
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_image_upscaler_Runwayml_image_upscaler_example %}

{% tab get_image_upscaler_Runwayml_image_upscaler_example 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
```
{% endtab %}

{% tab get_image_upscaler_Runwayml_image_upscaler_example 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;
```
{% endtab %}

{% tab get_image_upscaler_Runwayml_image_upscaler_example 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()
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> lipsync/voices
parent: Runway API v1
nav_order: 900
---
## Retrieve the list of available AI voices 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](../api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes 
  
##### Responses 

{% tabs get_lipsync-voices_Runwayml_lipsync-voices_response %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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"
    }
]
```
{% endtab %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_lipsync-voices_Runwayml_lipsync-voices_example %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/lipsync/voices/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_example 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});
```
{% endtab %}

{% tab get_lipsync-voices_Runwayml_lipsync-voices_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: Runway API v1
nav_order: 1700
---
## Retrieve the list of tasks currently being executed by the API
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-runwayml-v1/get-runwayml-tasks).    
Example <small>[…/tasks/?statuses=PENDING,RUNNING,THROTTLED&offset=0&limit=50](../api-runwayml-v1/get-runwayml-tasks)</small>.

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Responses 

{% tabs get_scheduler_Runwayml_scheduler_response %}

{% tab get_scheduler_Runwayml_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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>"
    }
]
```
{% endtab %}

{% tab get_scheduler_Runwayml_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
    taskId: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

{% tabs get_scheduler_Runwayml_scheduler_example %}

{% tab get_scheduler_Runwayml_scheduler_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_scheduler_Runwayml_scheduler_example 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});
```
{% endtab %}

{% tab get_scheduler_Runwayml_scheduler_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks/<code class="language-plaintext highlighter-rouge">taskId</code>
parent: Runway API v1
nav_order: 2000
---
## Retrieve task 
{: .no_toc }

<small>August 8, 2024 (December 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of

* [gen4_5/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4_5-create)
* [gen4turbo/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create)
* [gen4/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create)
* [gen4/upscale](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-upscale)
* [gen4/act-two](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two)
* [gen4/act-two-voice](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) 
* [gen4/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-video)
* [gen3turbo/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-actone)
* [gen3alpha/upscale](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale)
* [lipsync/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-lipsync-create)
* [frames/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create)

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path parameter
- `taskId` is **required**. Specify the taskId you want to retrieve.   

##### Responses 

{% tabs get_tasks_taskId_Runwayml_tasks_taskId_response %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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    
}
```
{% endtab %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_tasks_taskId_Runwayml_tasks_taskId_example %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/tasks/taskId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_example 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});
```
{% endtab %}

{% tab get_tasks_taskId_Runwayml_tasks_taskId_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks
parent: Runway API v1
nav_order: 1900
---
## Retrieve tasks 
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](../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 

{% tabs get_tasks_Runwayml_tasks_response %}

{% tab get_tasks_Runwayml_tasks_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
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    
}
```
{% endtab %}

{% tab get_tasks_Runwayml_tasks_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_tasks_Runwayml_tasks_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tasks_Runwayml_tasks_example %}

{% tab get_tasks_Runwayml_tasks_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email=email" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_tasks_Runwayml_tasks_example 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});
```
{% endtab %}

{% tab get_tasks_Runwayml_tasks_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> text_to_image_preview
nav_exclude: true
---
## Text to Image instant generation (Stable Diffusion) <span class="required-input-field"><b>(retired)</b></span> 
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

<span class="required-input-field"><b>Important</b></span>  
**Runway retired this endpoint in September 2025.  
Please use [POST frames/create](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.  

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `email` is optional when only one [account](../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 

{% tabs get_text_to_image_preview_Runwayml_text_to_image_preview_response %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```json
{
    "url": "<image url>",
    "seed": 1234567
}
```
{% endtab %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>  
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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_text_to_image_preview_Runwayml_text_to_image_preview_example %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_example Curl %}
``` bash
curl "https://api.useapi.net/v1/runwayml/text_to_image_preview/?text_prompt=happy cat" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_example 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});
```
{% endtab %}

{% tab get_text_to_image_preview_Runwayml_text_to_image_preview_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-transcribe ===
Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-transcribe
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> transcribe
parent: Runway API v1
nav_order: 1200
---
## Transcribe audio or video to text
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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. 

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Query Parameters
- `assetId` is **required**. Specify the audio or video assetId you want to transcribe. Use [GET /assets](../api-runwayml-v1/get-runwayml-assets) to see the list of assets. To upload a new audio/video asset use [POST /assets](../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 

{% tabs get_transcribe_Runwayml_transcribe_response %}

{% tab get_transcribe_Runwayml_transcribe_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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
}
```
{% endtab %}

{% tab get_transcribe_Runwayml_transcribe_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab get_transcribe_Runwayml_transcribe_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_transcribe_Runwayml_transcribe_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Not found.",
    "code": 404
}
```

{% endtab %}

{% endtabs %}

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

{% tabs get_transcribe_Runwayml_transcribe_example %}

{% tab get_transcribe_Runwayml_transcribe_example 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 …" 
```
{% endtab %}

{% tab get_transcribe_Runwayml_transcribe_example 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});
```
{% endtab %}

{% tab get_transcribe_Runwayml_transcribe_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/<code class="language-plaintext highlighter-rouge">email</code>
parent: Runway API v1
nav_order: 300
---
## Create or update Runway API account configuration
{: .no_toc }

<small>August 8, 2024</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **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](../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](../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 

{% tabs post_account_Runwayml_response %}

{% tab post_account_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

```json
{
  "email": "user-1@example.com",
  "password": "<password>",
  "maxJobs": 5,
  "jwt": {
    "token": "<token>",
    "exp": 1734858598.864,
    "iat": 1732266598.864,
    "id": 123456,
  }        
}
```

{% endtab %}

{% tab post_account_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_account_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_account_Runwayml_example %}

{% tab post_account_Runwayml_example 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": …}'
```
{% endtab %}

{% tab post_account_Runwayml_example 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});
```
{% endtab %}

{% tab post_account_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets ===
Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets
parent: Runway API v1
nav_order: 1500
---
## Upload the asset to your Runway account
{: .no_toc }

<small>August 8, 2024 (July 22, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](../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](../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](../api-runwayml-v1/post-runwayml-super_slow_motion).

##### Request Body

Provide content of the uploaded file as a binary data.

##### Responses 

{% tabs post_assets_Runwayml_assets_response %}

{% tab post_assets_Runwayml_assets_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  
```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
}
```
{% endtab %}

{% tab post_assets_Runwayml_assets_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_assets_Runwayml_assets_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_assets_Runwayml_assets_example %}

{% tab post_assets_Runwayml_assets_example 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
```
{% endtab %}

{% tab post_assets_Runwayml_assets_example 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});
```
{% endtab %}

{% tab post_assets_Runwayml_assets_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> frames/create
parent: Runway API v1
nav_order: 850
---
## Frames
{: .no_toc }

<small>January 29, 2025 (June 6, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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.

{: .post }
> **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](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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.  

 - `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 

{% tabs post_frames-create_Runwayml_response %}

{% tab post_frames-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_frames-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_frames-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_frames-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_frames-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_frames-create_Runwayml_example %}

{% tab post_frames-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_frames-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_frames-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen2/create
nav_order: 600
nav_exclude: true
---
## Create a 4-second-long video using text and/or image prompts
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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](../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.  

 - `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 

{% tabs post_gen2-create_Runwayml_response %}

{% tab post_gen2-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen2-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen2-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen2-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen2-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen2-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen2-create_Runwayml_example %}

{% tab post_gen2-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen2-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen2-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen2/extend
nav_order: 700
nav_exclude: true
---
## Extend the video by 4 seconds
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](../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](../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.  

 - `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 

{% tabs post_gen2-extend_Runwayml_response %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen2-extend_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen2-extend_Runwayml_example %}

{% tab post_gen2-extend_Runwayml_example 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": "…" }'
```
{% endtab %}

{% tab post_gen2-extend_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen2-extend_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3/actone
parent: Runway API v1
nav_order: 570
---
## Drive your image or video character performance using simple video and audio inputs.
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen3-actone_Runwayml_response %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3-actone_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3-actone_Runwayml_example %}

{% tab post_gen3-actone_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3-actone_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3-actone_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3/create
parent: Runway API v1
nav_order: 500
---
## Create a video using text and/or image prompts
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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.

{: .post }
> **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](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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](../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.  

 - `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 

{% tabs post_gen3-create_Runwayml_response %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen3-create_Runwayml_example %}

{% tab post_gen3-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3/extend
parent: Runway API v1
nav_order: 550
---
## Extend the Gen-3 Alpha video by 5 or 10 seconds
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-runwayml-v1/post-runwayml-gen3turbo-extend).

{: .post }
> **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](../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](../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](../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.  

 - `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 

{% tabs post_gen3-extend_Runwayml_response %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3-extend_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3-extend_Runwayml_example %}

{% tab post_gen3-extend_Runwayml_example 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": "…" }'
```
{% endtab %}

{% tab post_gen3-extend_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3-extend_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3/video
parent: Runway API v1
nav_order: 525
---
## Gen-3 Alpha Video to Video
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen3-video_Runwayml_response %}

{% tab post_gen3-video_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3-video_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3-video_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3-video_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3-video_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen3-video_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3-video_Runwayml_example %}

{% tab post_gen3-video_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3-video_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3-video_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3alpha/upscale
parent: Runway API v1
nav_order: 580
---
## Upscale to 4K the Gen-3 Alpha and Gen-3 Alpha Turbo videos
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to Upscale to 4K videos generated by

* [gen3turbo/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-actone)

{: .post }
> **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](../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](../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](../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.  

 - `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 

{% tabs post_Runwayml_gen3alpha-upscale_response %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_Runwayml_gen3alpha-upscale_example %}

{% tab post_Runwayml_gen3alpha-upscale_example 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": "…" }'
```
{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_example 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});
```
{% endtab %}

{% tab post_Runwayml_gen3alpha-upscale_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3turbo/actone
parent: Runway API v1
nav_order: 495
---
## Drive your image or video character performance using simple video and audio inputs.
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

<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](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](../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.

{: .post }
> **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](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen3turbo-actone_Runwayml_response %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3turbo-actone_Runwayml_example %}

{% tab post_gen3turbo-actone_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3turbo-actone_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3turbo/create
parent: Runway API v1
nav_order: 450
---
## Create a video using the first/middle/last image(s) with a text prompt and a camera control
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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](../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.  

 - `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 

{% tabs post_gen3turbo-create_Runwayml_response %}

{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen3turbo-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-video-using-the-first-andor-last-images-with-a-text-prompt) 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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen3turbo-create_Runwayml_example %}

{% tab post_gen3turbo-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3turbo-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3turbo-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3turbo/expand
parent: Runway API v1
nav_order: 490
---
## Expand Video (outpaint) with Gen-3 Alpha Turbo
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.  

{: .post }
> **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](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen3turbo-expand_Runwayml_response %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve videoAssetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3turbo-expand_Runwayml_example %}

{% tab post_gen3turbo-expand_Runwayml_example 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": "…" }'
```
{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3turbo-expand_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3turbo/extend
parent: Runway API v1
nav_order: 480
---
## Extend the Gen-3 Alpha Turbo video by 8 seconds
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../api-runwayml-v1/post-runwayml-gen3-extend).

{: .post }
> **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](../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](../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](../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.  

 - `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 

{% tabs post_gen3turbo-extend_Runwayml_response %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3turbo-extend_Runwayml_example %}

{% tab post_gen3turbo-extend_Runwayml_example 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": "…" }'
```
{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3turbo-extend_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen3turbo/video
parent: Runway API v1
nav_order: 470
---
## Gen-3 Alpha Turbo Video to Video
{: .no_toc }

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

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen3turbo-video_Runwayml_response %}

{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen3turbo-video_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen3turbo-video_Runwayml_example %}

{% tab post_gen3turbo-video_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen3turbo-video_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen3turbo-video_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/act-two-voice
parent: Runway API v1
nav_order: 448
---
## Create Act-Two voice swap
{: .no_toc }

<small>September 8, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](../api-runwayml-v1/post-runwayml-assets).  

- `voiceId` is **required**. Specify the voice ID to use for voice swap. Use [GET /lipsync/voices](../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](../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.  

 - `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 

{% tabs post_gen4-acttwvoice_Runwayml_response %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```

{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-act-two-voice-swap-videos-using-gen-4-with-video-and-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen4-acttwvoice_Runwayml_example %}

{% tab post_gen4-acttwvoice_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4-acttwvoice_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/act-two
parent: Runway API v1
nav_order: 447
---
## Create Act-Two videos using Gen-4 with driving video and character reference.
{: .no_toc }

<small>July 22, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](../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](../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](../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](../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.  

 - `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 

{% tabs post_gen4-acttwo_Runwayml_response %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```

{% endtab %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_gen4-acttwo_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_gen4-acttwo_Runwayml_example %}

{% tab post_gen4-acttwo_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen4-acttwo_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4-acttwo_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/create
parent: Runway API v1
nav_order: 440
---
## Create a video using the first image(s) with a text prompt
{: .no_toc }

<small>April 2, 2025 (July 22, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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.  

 - `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 

{% tabs post_gen4-create_Runwayml_response %}

{% tab post_gen4-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen4-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen4-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen4-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-video-using-the-first-andor-last-images-with-a-text-prompt) 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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen4-create_Runwayml_example %}

{% tab post_gen4-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen4-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/upscale
parent: Runway API v1
nav_order: 445
---
## Upscale to 4K the Gen-4, Gen-4 Turbo, Gen-3 Alpha and Gen-3 Alpha Turbo videos
{: .no_toc }

<small>April 7, 2025 (July 22, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to Upscale to 4K videos generated by

* [gen4turbo/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create)
* [gen4/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create)
* [gen3turbo/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-create)
* [gen3turbo/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-video)
* [gen3turbo/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend)
* [gen3turbo/expand](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand)
* [gen3turbo/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone)
* [gen3/create](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-create)
* [gen3/video](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-video)
* [gen3/extend](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-extend)
* [gen3/actone](https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen3-actone)

{: .post }
> **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](../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](../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](../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.  

 - `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 

{% tabs post_Runwayml_gen4-upscale_response %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_Runwayml_gen4-upscale_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_Runwayml_gen4-upscale_example %}

{% tab post_Runwayml_gen4-upscale_example 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": "…" }'
```
{% endtab %}

{% tab post_Runwayml_gen4-upscale_example 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});
```
{% endtab %}

{% tab post_Runwayml_gen4-upscale_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/video
parent: Runway API v1
nav_order: 445
---
## Create a video using Runway Gen-4 Aleph (video-to-video)
{: .no_toc }

<small>August 4, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

[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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](../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](../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](../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.  

 - `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 

{% tabs post_gen4-video_Runwayml_response %}

{% tab post_gen4-video_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4-video_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen4-video_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4-video_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen4-video_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen4-video_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen4-video_Runwayml_example %}

{% tab post_gen4-video_Runwayml_example 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"}'
```
{% endtab %}

{% tab post_gen4-video_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4-video_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4_5/create
parent: Runway API v1
nav_order: 410
---
## Create a video using text prompt or image
{: .no_toc }

<small>December 15, 2025 (January 23, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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.

 - `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

{% tabs post_gen4_5-create_Runwayml_response %}

{% tab post_gen4_5-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4_5-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen4_5-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4_5-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen4_5-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen4_5-create_Runwayml_example %}

{% tab post_gen4_5-create_Runwayml_example 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"}'
```
{% endtab %}

{% tab post_gen4_5-create_Runwayml_example 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"}'
```
{% endtab %}

{% tab post_gen4_5-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4_5-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4turbo/create
parent: Runway API v1
nav_order: 425
---
## Create a video using the first image(s) with a text prompt
{: .no_toc }

<small>April 7, 2025 (July 22, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../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.  

 - `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 

{% tabs post_gen4turbo-create_Runwayml_response %}

{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
  }
}
```

{% endtab %}

{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_gen4turbo-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-video-using-the-first-andor-last-images-with-a-text-prompt) 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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_gen4turbo-create_Runwayml_example %}

{% tab post_gen4turbo-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_gen4turbo-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_gen4turbo-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create
parent: Runway API v1
nav_order: 405
---
## Images
{: .no_toc }

<small>February 17, 2026 (March 5, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Unified image generation endpoint supporting multiple Runway models: [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`, [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](../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: 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 | optional | optional |

##### Model Comparison: GPT Image / Seedream

| Feature | GPT Image 1.5 | GPT Image 1 Mini | Seedream 5 |
|---------|:-------------:|:----------------:|:----------:|
| Reference images | 0–1 | 0–1 | 0–14 |
| Resolution | — | — | 2K, 3K |
| aspect_ratio | 1:1, 3:2, 2:3 | 1:1, 3:2, 2:3 | all except 4:5, 5:4 |
| text_prompt | **required** | **required** | optional |

##### Model Comparison: Gen-4

| Feature | Gen-4 | Gen-4 Turbo |
|---------|:----:|:----------:|
| Reference images | 0–3 | **1–3** (required) |
| Resolution | 1080p, 720p | 1080p |
| 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](../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.

{: .post }
> **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](../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: `nano-banana`, `nano-banana-2`, `nano-banana-pro`, `gpt-image-1-5`, `gpt-image-1-mini`, `seedream-5`, `gen4`, `gen4-turbo`.
  See [model comparison](#model-comparison) for details.

- `email` is optional, if not provided API will randomly select available [account](../api-runwayml-v1/get-runwayml-accounts).

- `text_prompt` describes your image in detail. **Required** for `gpt-image-1-5` and `gpt-image-1-mini`, optional for all other models.
  Maximum length 5000 characters.

- `aspect_ratio` is optional. Default `16:9`. Available values depend on model — see [model comparison](#model-comparison).
  All values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `4:5`, `5:4`, `3:2`, `2:3`.
  - GPT Image 1.5, GPT Image 1 Mini: `1:1`, `3:2`, `2:3`
  - 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.
  - Gen-4: `1080p` (default), `720p`
  - Gen-4 Turbo: `1080p`
  - 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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../api-runwayml-v1/post-runwayml-assets). Parameters can be referred in the prompt as `@IMG_1`, `@IMG_2`, etc.
  Maximum number of reference images depends on model — see [model comparison](#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. Only supported by Gen-4 and Gen-4 Turbo.
  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`.

- `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](../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.

 - `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

{% tabs post_images-create_Runwayml_response %}

{% tab post_images-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
    }
}
```

{% endtab %}

{% tab post_images-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_images-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_images-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_images-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_images-create_Runwayml_example %}

{% tab post_images-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_images-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_images-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> lipsync/create
parent: Runway API v1
nav_order: 800
---
## Create Lip Sync Video
{: .no_toc }

<small>August 8, 2024 (March 21, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of audio assets. To upload a new audio asset use [POST /assets](../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](../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](../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.  

 - `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 

{% tabs post_lipsync-create_Runwayml_response %}

{% tab post_lipsync-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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>"
}
```

{% endtab %}

{% tab post_lipsync-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_lipsync-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_lipsync-create_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_lipsync-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}


{% tab post_lipsync-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_lipsync-create_Runwayml_example %}

{% tab post_lipsync-create_Runwayml_example 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": "…"}'
```
{% endtab %}

{% tab post_lipsync-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_lipsync-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> super_slow_motion
parent: Runway API v1
nav_order: 730
---
## Super-Slow Motion
{: .no_toc }

<small>November 8, 2024 (March 21, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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.

{: .post }
> **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](../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](../api-runwayml-v1/get-runwayml-assets) to see the list of video assets. Use [POST /assets](../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](../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.  

 - `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 

{% tabs post_super_slow_motion_Runwayml_response %}

{% tab post_super_slow_motion_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
}
```

{% endtab %}

{% tab post_super_slow_motion_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_super_slow_motion_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_super_slow_motion_Runwayml_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>  

```json
{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}
```

{% endtab %}

{% tab post_super_slow_motion_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](#create-a-4-second-long-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."
}
```

{% endtab %}

{% endtabs %}

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

{% tabs post_super_slow_motion_Runwayml_example %}

{% tab post_super_slow_motion_Runwayml_example 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 }'
```
{% endtab %}

{% tab post_super_slow_motion_Runwayml_example 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});
```
{% endtab %}

{% tab post_super_slow_motion_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create
parent: Runway API v1
nav_order: 406
---
## Videos
{: .no_toc }

<small>March 5, 2026</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Unified video generation endpoint supporting multiple Runway models: [Gen-4.5](https://runwayml.com) `gen4.5`, [Gen-4](https://runwayml.com) `gen4`, [Gen-4 Turbo](https://runwayml.com) `gen4-turbo`, [Kling 3.0 Pro](https://klingai.com/) `kling-3.0-pro`, [Kling 3.0 Standard](https://klingai.com/) `kling-3.0-standard`, [Kling 2.6 Pro](https://klingai.com/) `kling-2.6-pro`, [Kling 2.6 I2V](https://klingai.com/) `kling-2.6-i2v`, [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`, [Wan 2.6 Flash](https://wan.video/) `wan-2.6-flash`, and [Wan 2.2 Animate](https://github.com/Wan-Video/Wan2.2) `wan-2.2-animate`.

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: 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 |

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

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](../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.

{: .post }
> **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](../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: `gen4.5`, `gen4`, `gen4-turbo`, `kling-3.0-pro`, `kling-3.0-standard`, `kling-2.6-pro`, `kling-2.6-i2v`, `veo-3.1`, `sora-2`, `sora-2-pro`, `wan-2.6-flash`, `wan-2.2-animate`.
  See [model comparison](#model-comparison-gen-45--gen-4) for details.

- `email` is optional, if not provided API will randomly select available [account](../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).

- `duration` is optional. Default is the first supported value for the model.
  - Gen-4.5: 2–10 (continuous range)
  - Gen-4, Gen-4 Turbo: `5`, `10`
  - Kling 3.0 Pro/Standard: `5`, `10`, `15`
  - Kling 2.6 Pro, Kling 2.6 I2V: `5`, `10`
  - Veo 3.1: `4`, `6`, `8`
  - Sora 2, Sora 2 Pro: `4`, `8`, `12`
  - Wan 2.6 Flash: `5`, `10`, `15`
  - Wan 2.2 Animate: not supported (auto)

- `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.
  - Gen-4, Gen-4 Turbo: `720p`
  - Veo 3.1: `720p` (default), `1080p`
  - Sora 2 Pro: `720p` (default), `1080p`
  - Wan 2.6 Flash: `720p` (default), `1080p`
  - All other models: not supported (resolution auto-selected)

- `audio` is optional. Default `true`. Set to `false` to disable audio generation.
  Supported by: Gen-4.5, Kling 3.0 Pro/Standard, Kling 2.6 Pro, Kling 2.6 I2V, Veo 3.1, Wan 2.6 Flash.

- `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` are optional. Specify the assetIds of reference images. Use [GET /assets/?mediaType=image](../api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](../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)

- `videoAssetId` is optional. Specify the assetId of a reference video. Only supported by `wan-2.2-animate` (required). Use [POST /assets](../api-runwayml-v1/post-runwayml-assets) to upload a video asset.

- `multishot_prompt_1` through `multishot_prompt_5` and `multishot_duration_1` through `multishot_duration_5` are optional. Multi-shot parameters for creating multi-scene videos. Only supported by Kling 3.0 Pro and Kling 3.0 Standard.
  Each shot requires both a prompt and a duration. Minimum 2 shots, maximum 5 shots. Shot duration range: 3–12 seconds. Total duration across all shots must not exceed 15 seconds.
  Prompt max length: 512 characters per shot.

- `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](../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.

 - `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

{% tabs post_videos-create_Runwayml_response %}

{% tab post_videos-create_Runwayml_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](../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`](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
    }
}
```

{% endtab %}

{% tab post_videos-create_Runwayml_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "<Error message>",
  "code": 400
}
```
{% endtab %}

{% tab post_videos-create_Runwayml_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_videos-create_Runwayml_response <span class="http-status-bad">412</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412" rel="noreferrer" target="_blank"><span class="http-status-bad">412 Insufficient credits</span></a>

You do not have enough credits to run this task.

```json
{
    "error": "You do not have enough credits to run this task."
}
```
{% endtab %}

{% tab post_videos-create_Runwayml_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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."
}
```

{% endtab %}


{% endtabs %}

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

{% tabs post_videos-create_Runwayml_example %}

{% tab post_videos-create_Runwayml_example 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}'
```
{% endtab %}

{% tab post_videos-create_Runwayml_example 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});
```
{% endtab %}

{% tab post_videos-create_Runwayml_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/start-here/setup-tempolor ===
Document URL: https://useapi.net/docs/start-here/setup-tempolor
---
layout: default
title: Setup TemPolor
parent: Start Here
nav_order: 260
---
# <img style="height:1.2em;vertical-align: middle;" src="https://useapi.net/assets/images/tempolor.png"> Setup TemPolor
{: .no_toc }

<small>May  15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

<small>Approximately 5 minutes to complete setup steps.</small>  

---

{: .note }
> This is the setup guide for [TemPolor API](../api-tempolor-v1). An active [TemPolor](https://www.tempolor.com) subscription and a [useapi.net subscription](../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](../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="https://useapi.net/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
---
layout: default
title: TemPolor API v1
nav_order: 8000
has_children: true
permalink: /docs/api-tempolor-v1
---

# <img style="height:1.5em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/assets/images/telegram.svg"> Telegram Channel</a>
* <a href="https://www.reddit.com/r/TemPolorAPI/"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/<code class="language-plaintext highlighter-rouge">user_id</code>
parent: TemPolor API v1
nav_order: 400
---
## Delete TemPolor API account
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a TemPolor API account configuration.

[Setup TemPolor](../../docs/start-here/setup-tempolor)

{: .delete }
> **https://api.useapi.net/v1/tempolor/accounts/`user_id`**

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

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

##### Responses 

{% tabs del_tempolor_accounts_user_id_response %}

{% tab del_tempolor_accounts_user_id_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>  

Account configuration was successfully deleted.

{% endtab %}

{% tab del_tempolor_accounts_user_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_tempolor_accounts_user_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Account configuration not found.

{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_tempolor_accounts_user_id_example %}

{% tab del_tempolor_accounts_user_id_example Curl %}
``` bash
curl -X DELETE https://api.useapi.net/v1/tempolor/accounts/<user_id> \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab del_tempolor_accounts_user_id_example 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);
```
{% endtab %}

{% tab del_tempolor_accounts_user_id_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/<code class="language-plaintext highlighter-rouge">job_id</code>
parent: TemPolor API v1
nav_order: 2100
---
## Cancel a running job
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .delete }
> **https://api.useapi.net/v1/tempolor/scheduler/<code class="language-plaintext highlighter-rouge">job_id</code>**

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

##### Path Parameters

- `job_id` is **required**. The job to cancel, as returned from [POST music/song](../api-tempolor-v1/post-tempolor-music-song), [POST music/instrumental](../api-tempolor-v1/post-tempolor-music-instrumental), or [GET scheduler](../api-tempolor-v1/get-tempolor-scheduler).

##### Responses 

{% tabs del_TemPolor_scheduler_job_id_response %}

{% tab del_TemPolor_scheduler_job_id_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a>  

Job was successfully cancelled.

{% endtab %}

{% tab del_TemPolor_scheduler_job_id_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

The job_id format is invalid.

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```
{% endtab %}

{% tab del_TemPolor_scheduler_job_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_TemPolor_scheduler_job_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

The specified job was not found or could not be cancelled.

```json
{
  "error": "Unable to locate running job_id",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

##### Examples

{% tabs del_TemPolor_scheduler_job_id_example %}

{% tab del_TemPolor_scheduler_job_id_example Curl %}
``` bash
curl -X DELETE "https://api.useapi.net/v1/tempolor/scheduler/<job_id>" \
  -H "Authorization: Bearer …"
```
{% endtab %}

{% tab del_TemPolor_scheduler_job_id_example 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);
}
```
{% endtab %}

{% tab del_TemPolor_scheduler_job_id_example 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}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/cloned-voices
parent: TemPolor API v1
nav_order: 1900
---
## Delete a cloned voice
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a previously created cloned voice.

{: .delete }
> **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](../start-here/setup-useapi) for details.   

##### Path Parameters

- `clonedVoiceItemId` is **required**. The cloned voice ID returned from a previous [POST music/cloned-voices](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) request.

##### Responses 

{% tabs delete_tempolor_music_cloned_voices_clonedVoiceItemId_response %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
  "result": true
}
```
{% endtab %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "clonedVoiceItemId has incorrect format",
  "code": 400
}
```
{% endtab %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "No record found for user:12345-tempolor:user_id-voice:abcdef123456789",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

{% tabs delete_tempolor_music_cloned_voices_clonedVoiceItemId_example %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_example Curl %}
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/cloned-voices/user:12345-tempolor:user_id-voice:abcdef123456789
```
{% endtab %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_example 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);
```
{% endtab %}

{% tab delete_tempolor_music_cloned_voices_clonedVoiceItemId_example 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')}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/<code class="language-plaintext highlighter-rouge">job_id</code>
parent: TemPolor API v1
nav_order: 1100
---
## Delete a music generation
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a previously generated music item.

{: .delete }
> **https://api.useapi.net/v1/tempolor/music/`job_id`**

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

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

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental) request.

##### Responses 

{% tabs delete_tempolor_music_job_id_response %}

{% tab delete_tempolor_music_job_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
  "result": true
}
```
{% endtab %}

{% tab delete_tempolor_music_job_id_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```
{% endtab %}

{% tab delete_tempolor_music_job_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_tempolor_music_job_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

{% tabs delete_tempolor_music_job_id_example %}

{% tab delete_tempolor_music_job_id_example Curl %}
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789
```
{% endtab %}

{% tab delete_tempolor_music_job_id_example 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);
```
{% endtab %}

{% tab delete_tempolor_music_job_id_example 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')}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/midi
parent: TemPolor API v1
nav_order: 1600
---
## Delete a MIDI file
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint deletes a previously uploaded MIDI file.

{: .delete }
> **https://api.useapi.net/v1/tempolor/music/midi/`midiItemId`**

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

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

##### Path Parameters

- `midiItemId` is **required**. The MIDI file ID returned from a previous [POST music/midi](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi) request.

##### Responses 

{% tabs delete_tempolor_music_midi_midiItemId_response %}

{% tab delete_tempolor_music_midi_midiItemId_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
  "result": true
}
```
{% endtab %}

{% tab delete_tempolor_music_midi_midiItemId_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "midiItemId has incorrect format",
  "code": 400
}
```
{% endtab %}

{% tab delete_tempolor_music_midi_midiItemId_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab delete_tempolor_music_midi_midiItemId_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "No record found for user:12345-tempolor:user_id-midi:abcdef123456789",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    error: string
    code: number
}
```

##### Examples

{% tabs delete_tempolor_music_midi_midiItemId_example %}

{% tab delete_tempolor_music_midi_midiItemId_example Curl %}
``` bash
curl -X DELETE -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/midi/user:12345-tempolor:user_id-midi:abcdef123456789
```
{% endtab %}

{% tab delete_tempolor_music_midi_midiItemId_example 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);
```
{% endtab %}

{% tab delete_tempolor_music_midi_midiItemId_example 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')}")
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/<code class="language-plaintext highlighter-rouge">user_id</code>
parent: TemPolor API v1
nav_order: 300
---
## Retrieve TemPolor API account configuration for `user_id`
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves the details of a specific TemPolor account.

[Setup TemPolor](../../docs/start-here/setup-tempolor)

{: .get }
> **https://api.useapi.net/v1/tempolor/accounts/`user_id`**

The `user_id` value should correspond to an account configured previously via a [POST accounts](post-tempolor-accounts) request.

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

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

##### Responses 

{% tabs get_tempolor_accounts_user_id_response %}

{% tab get_tempolor_accounts_user_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
  "user_id": "user_id1",
  "updated": 1715791234567,
  "updatedUTC": "2025-05-15T14:30:34.567Z",
  "maxJobs": 10,
  "requestParams": {}
}
```

{% endtab %}

{% tab get_tempolor_accounts_user_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_tempolor_accounts_user_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST accounts](https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts).

{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript
  user_id: string
  updated: number // timestamp in milliseconds
  updatedUTC: string // ISO date string
  maxJobs: number
  requestParams: {}
}
```

##### Examples

{% tabs get_tempolor_accounts_user_id_example %}

{% tab get_tempolor_accounts_user_id_example Curl %}
``` bash
curl https://api.useapi.net/v1/tempolor/accounts/<user_id> \
     -H "Accept: application/json" \
     -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_tempolor_accounts_user_id_example 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});
```
{% endtab %}

{% tab get_tempolor_accounts_user_id_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
parent: TemPolor API v1
nav_order: 200
---
## Get List of Accounts
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves the complete list of configured API accounts for TemPolor.

[Setup TemPolor](../../docs/start-here/setup-tempolor)

{: .get }
> **https://api.useapi.net/v1/tempolor/accounts**

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

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

##### Responses 

{% tabs get_tempolor_accounts_response %}

{% tab get_tempolor_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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": {} 
  }
}
```

{% endtab %}

{% tab get_tempolor_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_tempolor_accounts_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Returned when no accounts are configured.

{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript
  [user_id: string]: {
    user_id: string
    updated: number // timestamp in milliseconds
    updatedUTC: string // ISO date string
    maxJobs: number
    requestParams: {}
  }
}
```

##### Examples

{% tabs get_tempolor_accounts_example %}

{% tab get_tempolor_accounts_example Curl %}
``` bash
curl -H "Accept: application/json" \
     -H "Authorization: Bearer …" \
     -X GET https://api.useapi.net/v1/tempolor/accounts
```
{% endtab %}

{% tab get_tempolor_accounts_example 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});
```
{% endtab %}

{% tab get_tempolor_accounts_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/artist-voices
parent: TemPolor API v1
nav_order: 1300
---
## List artist voices
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) by providing the `artistVoiceItemId` parameter.

{: .get }
> **https://api.useapi.net/v1/tempolor/music/artist-voices/?...**

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

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

##### Query Parameters

- `user_id` is optional when only one [account](https://useapi.net/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 

{% tabs get_tempolor_music_artist_voices_response %}

{% tab get_tempolor_music_artist_voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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
}
```
{% endtab %}

{% tab get_tempolor_music_artist_voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tempolor_music_artist_voices_example %}

{% tab get_tempolor_music_artist_voices_example 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"
```
{% endtab %}

{% tab get_tempolor_music_artist_voices_example 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;
}
```
{% endtab %}

{% tab get_tempolor_music_artist_voices_example 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
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/cloned-voices
parent: TemPolor API v1
nav_order: 1800
---
## List cloned voices
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of cloned voices that you've previously created using [POST music/cloned-voices](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices). These cloned voices can be used in music generation with [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song).

{: .get }
> **https://api.useapi.net/v1/tempolor/music/cloned-voices/?...**

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

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

##### Query Parameters

- `user_id` is optional when only one [account](https://useapi.net/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 

{% tabs get_tempolor_music_cloned_voices_response %}

{% tab get_tempolor_music_cloned_voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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": ""
}
```
{% endtab %}

{% tab get_tempolor_music_cloned_voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tempolor_music_cloned_voices_example %}

{% tab get_tempolor_music_cloned_voices_example 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"
```
{% endtab %}

{% tab get_tempolor_music_cloned_voices_example 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;
}
```
{% endtab %}

{% tab get_tempolor_music_cloned_voices_example 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
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/download/<code class="language-plaintext highlighter-rouge">job_id</code>
parent: TemPolor API v1
nav_order: 1200
---
## Download generated music
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-job_id).

{: .get }
> **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](../start-here/setup-useapi) for details.   

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](https://useapi.net/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 

{% tabs get_tempolor_music_download_job_id_response %}

{% tab get_tempolor_music_download_job_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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.
{% endtab %}

{% tab get_tempolor_music_download_job_id_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Generation is not completed yet (0)",
  "code": 400
}
```
{% endtab %}

{% tab get_tempolor_music_download_job_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_tempolor_music_download_job_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    url: string
    remainSeconds: number
    error: string
    code: number
}
```

##### Examples

{% tabs get_tempolor_music_download_job_id_example %}

{% tab get_tempolor_music_download_job_id_example 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"
```
{% endtab %}

{% tab get_tempolor_music_download_job_id_example 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);
}
```
{% endtab %}

{% tab get_tempolor_music_download_job_id_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/<code class="language-plaintext highlighter-rouge">job_id</code>
parent: TemPolor API v1
nav_order: 1000
---
## Check music generation status and results
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint checks the status of a previously submitted music generation job. The `job_id` is returned from [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental).

{: .get }
> **https://api.useapi.net/v1/tempolor/music/`job_id`**

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

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

##### Path Parameters

- `job_id` is **required**. The job returned from a previous [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](https://useapi.net/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`](https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-download-job_id) endpoint.

##### Responses 

{% tabs get_tempolor_music_job_id_response %}

{% tab get_tempolor_music_job_id_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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

{% endtab %}

{% tab get_tempolor_music_job_id_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "job_id has incorrect format",
  "code": 400
}
```
{% endtab %}

{% tab get_tempolor_music_job_id_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_tempolor_music_job_id_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789",
  "code": 404
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tempolor_music_job_id_example %}

{% tab get_tempolor_music_job_id_example Curl %}
``` bash
curl -H "Authorization: Bearer …" \
     https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789
```
{% endtab %}

{% tab get_tempolor_music_job_id_example 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));
  }
}
```
{% endtab %}

{% tab get_tempolor_music_job_id_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/midi
parent: TemPolor API v1
nav_order: 1500
---
## List MIDI files
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint retrieves a list of MIDI files that you've previously uploaded using [POST music/midi](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi). These MIDI files can be used as templates for music generation with [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song).

{: .get }
> **https://api.useapi.net/v1/tempolor/music/midi/?...**

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

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

##### Query Parameters

- `user_id` is optional when only one [account](https://useapi.net/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 

{% tabs get_tempolor_music_midi_response %}

{% tab get_tempolor_music_midi_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```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": ""
}
```
{% endtab %}

{% tab get_tempolor_music_midi_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tempolor_music_midi_example %}

{% tab get_tempolor_music_midi_example 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"
```
{% endtab %}

{% tab get_tempolor_music_midi_example 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;
}
```
{% endtab %}

{% tab get_tempolor_music_midi_example 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
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music
parent: TemPolor API v1
nav_order: 900
---
## List music generation jobs
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **https://api.useapi.net/v1/tempolor/music/?...**

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

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

##### Query Parameters

- `user_id` is optional when only one [account](https://useapi.net/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 

{% tabs get_tempolor_music_response %}

{% tab get_tempolor_music_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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

{% endtab %}

{% tab get_tempolor_music_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Invalid type parameter. Must be 'song' or 'instrumental'",
  "code": 400
}
```
{% endtab %}

{% tab get_tempolor_music_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_tempolor_music_example %}

{% tab get_tempolor_music_example 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"
```
{% endtab %}

{% tab get_tempolor_music_example 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;
}
```
{% endtab %}

{% tab get_tempolor_music_example 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
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available
parent: TemPolor API v1
nav_order: 2000
---
## Get available capacity
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Get information about currently executing jobs and available capacity for all configured accounts.

{: .get }
> **https://api.useapi.net/v1/tempolor/scheduler/available**

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

##### Responses 

{% tabs get_TemPolor_scheduler_available_response %}

{% tab get_TemPolor_scheduler_available_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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
    }
  ]
}
```
{% endtab %}

{% tab get_TemPolor_scheduler_available_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_TemPolor_scheduler_available_example %}

{% tab get_TemPolor_scheduler_available_example Curl %}
``` bash
curl "https://api.useapi.net/v1/tempolor/scheduler/available" \
  -H "Authorization: Bearer …"
```
{% endtab %}

{% tab get_TemPolor_scheduler_available_example 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)`);
}
```
{% endtab %}

{% tab get_TemPolor_scheduler_available_example 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)")
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler ===
Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
parent: TemPolor API v1
nav_order: 1900
---
## List scheduled jobs
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Get a list of currently executing music generation jobs.

{: .get }
> **https://api.useapi.net/v1/tempolor/scheduler/**

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

##### Responses 

{% tabs get_TemPolor_scheduler_response %}

{% tab get_TemPolor_scheduler_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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"
  }
]
```
{% endtab %}

{% tab get_TemPolor_scheduler_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs get_TemPolor_scheduler_example %}

{% tab get_TemPolor_scheduler_example Curl %}
``` bash
curl "https://api.useapi.net/v1/tempolor/scheduler/" \
  -H "Authorization: Bearer …"
```
{% endtab %}

{% tab get_TemPolor_scheduler_example 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);
```
{% endtab %}

{% tab get_TemPolor_scheduler_example 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)
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts ===
Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
parent: TemPolor API v1
nav_order: 100
---
## Create or update TemPolor API account
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint configures a TemPolor API account with the provided credentials.

[Setup TemPolor](../../docs/start-here/setup-tempolor)

{: .post }
> **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](../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 

{% tabs post_tempolor_accounts_response %}

{% tab post_tempolor_accounts_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

```json
{
  "user_id": "123456789",
  "updated": 1715791234567,
  "updatedUTC": "2025-05-15T14:30:34.567Z",
  "maxJobs": 10,
  "requestParams": {}
}
```

{% endtab %}

{% tab post_tempolor_accounts_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter requestParams is required",
  "code": 400
}
```
{% endtab %}

{% tab post_tempolor_accounts_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_tempolor_accounts_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>
```json
{
  "error": "Subscription required",
  "code": 402
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript
  user_id: string
  updated: number // timestamp in milliseconds
  updatedUTC: string // ISO date string
  maxJobs: number
  requestParams: {}
}
```

##### Examples

{% tabs post_tempolor_accounts_example %}

{% tab post_tempolor_accounts_example 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
     }'
```
{% endtab %}

{% tab post_tempolor_accounts_example 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});
```
{% endtab %}

{% tab post_tempolor_accounts_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/cloned-voices
parent: TemPolor API v1
nav_order: 1700
---
## Upload voice sample for cloning
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint uploads an audio sample for voice cloning, which can then be used in the [POST music/song](https://useapi.net/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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](https://useapi.net/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 

{% tabs post_tempolor_music_cloned_voices_response %}

{% tab post_tempolor_music_cloned_voices_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

The cloned voice is immediately available to use in [POST music/song](https://useapi.net/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"
}
```
{% endtab %}

{% tab post_tempolor_music_cloned_voices_response <span class="http-status-good">202</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202" rel="noreferrer" target="_blank"><span class="http-status-good">202 Accepted</span></a>  

The voice cloning process is still in progress. Check back later using [GET music/cloned-voices](https://useapi.net/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."
}
```
{% endtab %}

{% tab post_tempolor_music_cloned_voices_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Empty file received",
  "code": 400
}
```
{% endtab %}

{% tab post_tempolor_music_cloned_voices_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemId: string
    clonedVoiceItemId: string
    message: string
    error: string
    code: number
}
```

##### Examples

{% tabs post_tempolor_music_cloned_voices_example %}

{% tab post_tempolor_music_cloned_voices_example 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
```
{% endtab %}

{% tab post_tempolor_music_cloned_voices_example 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});
```
{% endtab %}

{% tab post_tempolor_music_cloned_voices_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/instrumental
parent: TemPolor API v1
nav_order: 700
---
## Create instrumental music
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint generates instrumental music based on a text prompt and optional musical parameters.

{: .post }
> **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](../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.

- `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](https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts).

##### Responses 

{% tabs post_tempolor_music_instrumental_response %}

{% tab post_tempolor_music_instrumental_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](https://useapi.net/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
}
```
{% endtab %}

{% tab post_tempolor_music_instrumental_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter prompt is required",
  "code": 400
}
```
{% endtab %}

{% tab post_tempolor_music_instrumental_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_tempolor_music_instrumental_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>
```json
{
  "error": "Subscription required",
  "code": 402
}
```
{% endtab %}

{% tab post_tempolor_music_instrumental_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](https://useapi.net/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
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemIds: string[]
    jobs: string[]
    remainSeconds: number
    maxGenCountAtOnce: number
    unlimited: boolean
    remainNum: number
    totalNum: number
}
```

##### Examples

{% tabs post_tempolor_music_instrumental_example %}

{% tab post_tempolor_music_instrumental_example 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"}'
```
{% endtab %}

{% tab post_tempolor_music_instrumental_example 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});
```
{% endtab %}

{% tab post_tempolor_music_instrumental_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/midi
parent: TemPolor API v1
nav_order: 1400
---
## Upload MIDI file
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint uploads a MIDI file that can be used as a base for music generation in the [POST music/song](https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song) endpoint.

[POST raw content using Make.com and similar nocode tools.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](https://useapi.net/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 

{% tabs post_tempolor_music_midi_response %}

{% tab post_tempolor_music_midi_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

The MIDI file is immediately available to use in [POST music/song](https://useapi.net/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://..."
  }
}
```
{% endtab %}

{% tab post_tempolor_music_midi_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
  "error": "Content-Type must be audio/midi or audio/x-midi",
  "code": 400
}
```
{% endtab %}

{% tab post_tempolor_music_midi_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_tempolor_music_midi_example %}

{% tab post_tempolor_music_midi_example 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
```
{% endtab %}

{% tab post_tempolor_music_midi_example 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});
```
{% endtab %}

{% tab post_tempolor_music_midi_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/song
parent: TemPolor API v1
nav_order: 600
---
## Create music with vocals
{: .no_toc }

<small>May 15, 2025 (March 21, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

This endpoint generates a complete song with vocals based on a text prompt and optional parameters.

{: .post }
> **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](../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](https://useapi.net/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](https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-cloned-voices).
  - To create a new cloned voice, upload an audio sample using [POST cloned-voices](https://useapi.net/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](https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-midi).
  - To upload a new MIDI file, use [POST midi](https://useapi.net/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.

- `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](https://useapi.net/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 

{% tabs post_tempolor_music_song_response %}

{% tab post_tempolor_music_song_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](https://useapi.net/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
}
```
{% endtab %}

{% tab post_tempolor_music_song_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
  "error": "Parameter prompt is required",
  "code": 400
}
```
{% endtab %}

{% tab post_tempolor_music_song_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_tempolor_music_song_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>
```json
{
  "error": "Subscription required",
  "code": 402
}
```
{% endtab %}

{% tab post_tempolor_music_song_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
  "error": "The source material does not exist.",
  "code": 404
}
```

This error may occur if the specified `artistVoiceItemId`, `clonedVoiceItemId`, or `midiItemId` no longer exists.
{% endtab %}

{% tab post_tempolor_music_song_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>  

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](https://useapi.net/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
}
```
{% endtab %}

{% endtabs %}

##### Model 

```typescript
{   // TypeScript, all fields are optional
    result: boolean
    itemIds: string[]
    jobs: string[]
    remainSeconds: number
    maxGenCountAtOnce: number
    unlimited: boolean
    remainNum: number
    totalNum: number
}
```

##### Examples

{% tabs post_tempolor_music_song_example %}

{% tab post_tempolor_music_song_example 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"}'
```
{% endtab %}

{% tab post_tempolor_music_song_example 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});
```
{% endtab %}

{% tab post_tempolor_music_song_example 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())
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/stems-splitter
parent: TemPolor API v1
nav_order: 800
---
## Split audio into stems
{: .no_toc }

<small>May 15, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.](../questions-and-answers.html#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)

{: .post }
> **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](../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](../api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

{% tabs post_TemPolor_music_stems_splitter_response %}

{% tab post_TemPolor_music_stems_splitter_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>  

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"
}
```
{% endtab %}

{% tab post_TemPolor_music_stems_splitter_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

The server encountered an error processing your request.

```json
{
    "error": "<Error message>",
    "code": 400
}
```
{% endtab %}

{% tab post_TemPolor_music_stems_splitter_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

{% tabs post_TemPolor_music_stems_splitter_example %}

{% tab post_TemPolor_music_stems_splitter_example 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
```
{% endtab %}

{% tab post_TemPolor_music_stems_splitter_example 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});
```
{% endtab %}

{% tab post_TemPolor_music_stems_splitter_example 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)
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2 ===
Document URL: https://useapi.net/docs/api-v2
---
layout: default
title: Midjourney API v2
nav_order: 12000
has_children: true
permalink: /docs/api-v2
---

# <img style="height:2em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="https://useapi.net/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="https://useapi.net/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
---
layout: default
title: 🔓 CAPTCHA Solver
parent: Midjourney API v2
nav_order: 5000
---
# CAPTCHA Solver
{: .no_toc }

<small>December 8, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](https://useapi.net/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](https://useapi.net/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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> …/midjourney/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v2
nav_order: 600
---
## Delete Midjourney account
{: .no_toc }

<small>December 2023</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .delete }
> **https://api.useapi.net/v2/account/midjourney/`channel`**

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

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

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

##### Responses 

{% tabs del_account_midjourney_response %}

{% tab del_account_midjourney_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab del_account_midjourney_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab del_account_midjourney_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs del_account_midjourney_example %}

{% tab del_account_midjourney_example 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> 
```
{% endtab %}

{% tab del_account_midjourney_example 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});
```
{% endtab %}

{% tab del_account_midjourney_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-account-midjourney-channel ===
Document URL: https://useapi.net/docs/api-v2/get-account-midjourney-channel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> …/midjourney/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v2
nav_order: 400
---
## Retrieve Midjourney configuration for `channel` 
{: .no_toc }

<small>December 2023 (May 5, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v2/account/midjourney/`channel`**

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

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

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

##### Responses 

{% tabs get_account_midjourney_channel_response %}

{% tab get_account_midjourney_channel_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```json
{
  "channel": "Discord channel id",
  "discord": "Discord token",
  "maxJobs": 1-15
}
```
{% endtab %}

{% tab get_account_midjourney_channel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab get_account_midjourney_channel_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  discord: string, 
  channel: string,
  maxJobs: number,
  pendingModMessage: string
}
```

##### Examples

{% tabs get_account_midjourney_channel_example %}

{% tab get_account_midjourney_channel_example Curl %}
``` bash
curl https://api.useapi.net/v2/account/midjourney/<channel> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab get_account_midjourney_channel_example 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});
```
{% endtab %}

{% tab get_account_midjourney_channel_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-account-midjourney ===
Document URL: https://useapi.net/docs/api-v2/get-account-midjourney
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> account/midjourney
parent: Midjourney API v2
nav_order: 300
---
## Retrieve Midjourney accounts information
{: .no_toc }

<small>December 2023 (May 5, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .get }
> **https://api.useapi.net/v2/account/midjourney**

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

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

##### Responses 

{% tabs account_midjourney_response %}

{% tab account_midjourney_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>
```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
    }    
}
```
{% endtab %}

{% tab account_midjourney_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab account_midjourney_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

Configuration not found. To create configuration use [POST account/midjourney](post-account-midjourney).

{% endtab %}

{% endtabs %}

##### Model 
```typescript
{ // TypeScript, all fields are optional
  [channel: string]: {
    discord: string, 
    channel: string,
    maxJobs: number,
    pendingModMessage: string
  }
}
```

##### Examples

{% tabs account_midjourney_example %}

{% tab account_midjourney_example Curl %}
``` bash
curl https://api.useapi.net/v2/account/midjourney \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab account_midjourney_example 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});
```
{% endtab %}

{% tab account_midjourney_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-jobs-cancel ===
Document URL: https://useapi.net/docs/api-v2/get-jobs-cancel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/cancel/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Midjourney API v2
nav_order: 2100
---

## Cancel Midjourney job
{: .no_toc }

<small>December 2023 (October 7, 2024)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Cancel execution of job created by 
- [jobs/imagine](../api-v2/post-jobs-imagine)
- [jobs/button](../api-v2/post-jobs-button)
- [jobs/blend](../api-v2/post-jobs-blend)
- [jobs/describe](../api-v2/post-jobs-describe)
- [jobs/seed_async](../api-v2/post-jobs-seed_async)

{: .get }
> **https://api.useapi.net/v2/jobs/cancel/?jobid=`jobid`**

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

##### Query Parameter
`jobid` is **required**, use value returned by 
  - [jobs/imagine](../api-v2/post-jobs-imagine)
  - [jobs/button](../api-v2/post-jobs-button)
  - [jobs/blend](../api-v2/post-jobs-blend)
  - [jobs/describe](../api-v2/post-jobs-describe)
  - [jobs/seed_async](../api-v2/post-jobs-seed_async)

##### Responses 
{:toc}

{% tabs post_cancel_response %}

{% tab post_cancel_response <span class="http-status-good">200</span> %}

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

{% endtab %}

{% tab post_cancel_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% endtab %}

{% tab post_cancel_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_cancel_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}


{% tab post_cancel_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs cancel_example %}

{% tab cancel_example Curl %}
``` bash
curl https://api.useapi.net/v2/jobs/cancel/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab cancel_example 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});
```
{% endtab %}

{% tab cancel_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-jobs-jobid ===
Document URL: https://useapi.net/docs/api-v2/get-jobs-jobid
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/?jobid=<code class="language-plaintext highlighter-rouge">jobid</code>
parent: Midjourney API v2
nav_order: 1900
---

## Retrieve job status and results
{: .no_toc }

<small>December 2023 (September 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to retrieve status and results of 
- [jobs/imagine](post-jobs-imagine)
- [jobs/button](post-jobs-button)
- [jobs/blend](post-jobs-blend)
- [jobs/describe](post-jobs-describe)
- [jobs/info](post-jobs-info)
- [jobs/relax](post-jobs-relax)
- [jobs/fast](post-jobs-fast)
- [jobs/turbo](post-jobs-turbo)
- [jobs/variability](post-jobs-variability)
- [jobs/remix](post-jobs-remix)
- [jobs/seed_async](post-jobs-seed_async)

If you specified optional parameter [`replyUrl`](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.

{: .get }
> **https://api.useapi.net/v2/jobs/?jobid=`jobid`**

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

##### Query Parameter
`jobid` is **required**, use the value returned by the following jobs:
  - [jobs/imagine](post-jobs-imagine)
  - [jobs/button](post-jobs-button)
  - [jobs/blend](post-jobs-blend)
  - [jobs/describe](post-jobs-describe)
  - [jobs/seed_async](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](post-jobs-info)
  - [jobs/relax](post-jobs-relax) 
  - [jobs/fast](post-jobs-fast)
  - [jobs/turbo](post-jobs-turbo)
  - [jobs/variability](post-jobs-variability)
  - [jobs/remix](post-jobs-remix)

##### Responses 
{:toc}

{% tabs post_job_response %}

{% tab post_job_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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](../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](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
}
```
{% endtab %}

{% tab post_job_response <span class="http-status-bad">400</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

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

{% tab post_job_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_job_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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


{% tab post_job_response <span class="http-status-bad">404</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

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

{% endtab %}

{% tab post_job_response <span class="http-status-bad">410</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410" rel="noreferrer" target="_blank"><span class="http-status-bad">410 Gone</span></a>

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

{% endtab %}

{% endtabs %}

##### Model

To learn more about `status: moderated`, see [Midjourney moderation system](../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

{% tabs job_example %}

{% tab job_example Curl %}
``` bash
curl https://api.useapi.net/v2/jobs/?jobid=… \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab job_example 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});
```
{% endtab %}

{% tab job_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-jobs ===
Document URL: https://useapi.net/docs/api-v2/get-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs
parent: Midjourney API v2
nav_order: 2200
---

## Get list of currently executing Midjourney jobs
{: .no_toc }

<small>December 2023</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

{: .get }
> **https://api.useapi.net/v2/jobs**

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

##### Responses 
{:toc}

{% tabs post_jobs_response %}

{% tab post_jobs_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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

{% endtab %}

{% tab post_jobs_response <span class="http-status-bad">401</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% endtab %}

{% tab post_jobs_response <span class="http-status-bad">402</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs jobs_example %}

{% tab jobs_example Curl %}
``` bash
curl https://api.useapi.net/v2/jobs \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```
{% endtab %}

{% tab jobs_example 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});
```
{% endtab %}

{% tab jobs_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/get-proxy-cdn-midjourney ===
Document URL: https://useapi.net/docs/api-v2/get-proxy-cdn-midjourney
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> proxy/cdn-midjourney
parent: Midjourney API v2
nav_order: 2300
---
## Proxy asset retrieval from https://cdn.midjourney.com
{: .no_toc }

<small>September 12, 2025</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](../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:

{% tabs  direct_cdn_access %}

{% tab  direct_cdn_access 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
```
{% endtab %}

{% tab  direct_cdn_access 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));
```
{% endtab %}

{% tab  direct_cdn_access 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)
```
{% endtab %}

{% endtabs %}

**Note:** The `User-Agent` header is critical—without it, Cloudflare will block your request.

---

{: .get }
> **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](../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 

{% tabs proxy_cdn_midjourney_response %}

{% tab proxy_cdn_midjourney_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Returns the proxied content from the Midjourney CDN with appropriate headers.

{% endtab %}

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": "<Error message>",
    "code": 400
}
```

{% endtab %}

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab proxy_cdn_midjourney_response <span class="http-status-bad">403</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403" rel="noreferrer" target="_blank"><span class="http-status-bad">403 Forbidden</span></a>

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.

{% endtab %}

{% endtabs %}

##### Examples

{% tabs  get_proxy_cdn_midjourney_example %}

{% tab  get_proxy_cdn_midjourney_example Curl %}
``` bash
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/proxy/cdn-midjourney/?cdnUrl=https://cdn.midjourney.com/example-image.jpg"
```
{% endtab %}

{% tab  get_proxy_cdn_midjourney_example 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});
```
{% endtab %}

{% tab  get_proxy_cdn_midjourney_example 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)
```
{% endtab %}

{% endtabs %}


=== 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
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/<code class="language-plaintext highlighter-rouge">channel</code>/reset
parent: Midjourney API v2
nav_order: 700
---
## Reset `pendingModMessage` field for Midjourney account `channel` 
{: .no_toc }

<small>December 2023 (March 3, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **https://api.useapi.net/v2/account/midjourney/`channel`/reset**

The `channel` value should correspond to an account configured previously via a [POST](post-account-midjourney-reset-channel) request.

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

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

##### Responses 

{% tabs post_account_midjourney_reset_response %}

{% tab post_account_midjourney_reset_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab post_account_midjourney_reset_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_account_midjourney_reset_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>

{% endtab %}

{% tab post_account_midjourney_reset_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](https://useapi.net/docs/api-v2/del-account-midjourney-channel) and configure a new Discord account.

{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_account_midjourney_reset_example %}

{% tab post_account_midjourney_reset_example 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 
```
{% endtab %}

{% tab post_account_midjourney_reset_example 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});
```
{% endtab %}

{% tab post_account_midjourney_reset_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel ===
Document URL: https://useapi.net/docs/api-v2/post-account-midjourney-channel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> …/midjourney/<code class="language-plaintext highlighter-rouge">channel</code>
parent: Midjourney API v2
nav_order: 500
nav_exclude: true
---
## Create or update Midjourney account information <span class="required-input-field"><b>(retired)</b></span>  
{: .no_toc }

<small>December 2023 (August 5, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

<span class="required-input-field"><b>Important</b></span>  
**We will be officially sunsetting this endpoint in January 2025.  
Please use [POST account/midjourney](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.

{: .post }
> **https://api.useapi.net/v2/account/midjourney/`channel`**

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

- `API token` is **required**, see [Setup useapi.net](../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](../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 

{% tabs post_account_midjourney_channel_response %}

{% tab post_account_midjourney_channel_response <span class="http-status-good">204</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204" rel="noreferrer" target="_blank"><span class="http-status-good">204 No Content</span></a> 

{% endtab %}

{% tab post_account_midjourney_channel_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```
{% endtab %}

{% tab post_account_midjourney_channel_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_account_midjourney_channel_example %}

{% tab post_account_midjourney_channel_example 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": …}'
```
{% endtab %}

{% tab post_account_midjourney_channel_example 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});
```
{% endtab %}

{% tab post_account_midjourney_channel_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-account-midjourney ===
Document URL: https://useapi.net/docs/api-v2/post-account-midjourney
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> account/midjourney
parent: Midjourney API v2
nav_order: 350
---
## Create or update Midjourney account information
{: .no_toc }

<small>December 2023 (August 5, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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.

{: .post }
> **https://api.useapi.net/v2/account/midjourney**

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

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

##### Request Body
```json
{
    "discord": "Discord token",
    "maxJobs": 1-15,
}
```

- `discord` is **required**. Please see [Setup Midjourney](../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 

{% tabs post_account_midjourney_response %}

{% tab post_account_midjourney_response <span class="http-status-good">200</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a> 

Existing Midjourney API account was updated.

```json 
{
    "discord": "<discord token>",
    "channel": "<Midjourney private channel id>",
    "maxJobs": 1-15
}
```

{% endtab %}

{% tab post_account_midjourney_response <span class="http-status-good">201</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201" rel="noreferrer" target="_blank"><span class="http-status-good">201 Created</span></a> 

New Midjourney API account was created.

```json 
{
    "discord": "<discord token>",
    "channel": "<Midjourney private channel id>",
    "maxJobs": 1-15
}
```

{% endtab %}

{% tab post_account_midjourney_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```
{% endtab %}

{% tab post_account_midjourney_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
  "error": "Unauthorized",
  "code": 401
}
```
{% endtab %}

{% tab post_account_midjourney_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

```json
{
    "error": 
        "Account has no subscription or subscription expired"
        "Subscription quantity exceeded, see https://useapi.net/docs/subscription",
    "code": 402
}
```
{% endtab %}

{% endtabs %}

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

##### Examples

{% tabs post_account_midjourney_example %}

{% tab post_account_midjourney_example 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": …}'
```
{% endtab %}

{% tab post_account_midjourney_example 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});
```
{% endtab %}

{% tab post_account_midjourney_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-blend ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-blend
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/blend
parent: Midjourney API v2
nav_order: 1000
---
## Midjourney [/blend](https://docs.midjourney.com/docs/blend) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/blend](https://docs.midjourney.com/docs/blend) command to your [Discord Midjourney channel](../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=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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](../api-v2/get-account-midjourney) will be used. See [Setup Midjourney](../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](../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](../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 

{% tabs post_blend_response %}

{% tab post_blend_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span>

Use returned `jobid` to [retrieve job status and results](../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](https://useapi.net/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
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
    "error": "Unauthorized",
    "code": 401
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_blend_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated image link, see [Midjourney moderation system](../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
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_blend_response <span class="http-status-bad">504</span> %}
<span class="http-status-bad">504 Job queued</span>

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
}
```
{% endtab %}

{% tab post_blend_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs blend_example %}

{% tab blend_example 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": "…"}'
```
{% endtab %}

{% tab blend_example 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});
```
{% endtab %}

{% tab blend_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-button ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-button
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/button
parent: Midjourney API v2
nav_order: 900
---
## 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
{: .no_toc }

<small>December 2023 (February 19, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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*](../api-v2/get-jobs-jobid#model)) [jobs/imagine](../api-v2/post-jobs-imagine), [jobs/button](#midjourney-upscale-or-create-variations-and-enhance-or-modify-buttons) or [jobs/blend](../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](https://useapi.net/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](../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 

{% tabs post_button_response %}

{% tab post_button_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve job status and results](../api-v2/get-jobs-jobid).

If you want to retrieve four separate upscaled images once job completed successfully execute [seed_async](https://useapi.net/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
}
```

{% endtab %}

{% tab post_button_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```

{% endtab %}

{% tab post_button_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
    "error": "Unauthorized",
    "code": 401
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_button_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
    "error": "Unable to locate job <jobid>",
    "code": 404
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">409</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409" rel="noreferrer" target="_blank"><span class="http-status-bad">409 Conflict</span></a>
```json
{
  "error": "Button <U1 | U2 | U3 | U4> already executed by job <jobid>",
  "button": "<button>",
  "jobid": "<jobid>",
  "code": 409
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params, see [Midjourney moderation system](../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
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_button_response <span class="http-status-bad">504</span> %}
<span class="http-status-bad">504 Job queued</span>

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
}
```
{% endtab %}

{% tab post_button_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs button_example %}

{% tab button_example 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": "…"}'
```
{% endtab %}

{% tab button_example 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});
```
{% endtab %}

{% tab button_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-describe ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-describe
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/describe
parent: Midjourney API v2
nav_order: 1100
---
## Midjourney [/describe](https://docs.midjourney.com/docs/describe) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/describe](https://docs.midjourney.com/docs/describe) command to your [Discord Midjourney channel](../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=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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](../api-v2/get-account-midjourney) will be used. See [Setup Midjourney](../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](../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](../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 

{% tabs post_describe_response %}

{% tab post_describe_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve job status and results](../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
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
    "error": "Unauthorized",
    "code": 401
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_describe_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated image link, see [Midjourney moderation system](../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
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_describe_response <span class="http-status-bad">504</span> %}
<span class="http-status-bad">504 Job queued</span>

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
}
```
{% endtab %}

{% tab post_describe_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs describe_example %}

{% tab describe_example 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": "…"}'
```
{% endtab %}

{% tab describe_example 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});
```
{% endtab %}

{% tab describe_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-fast ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-fast
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/fast
parent: Midjourney API v2
nav_order: 1400
---
## Midjourney [/fast](https://docs.midjourney.com/docs/fast-relax) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/fast](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](../api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](../api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_fast_response %}

{% tab post_fast_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_fast_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_fast_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_fast_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_fast_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_fast_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs  info_example %}

{% tab  info_example 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": "…"}'
```
{% endtab %}

{% tab  info_example 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});
```
{% endtab %}

{% tab  info_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-imagine ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-imagine
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/imagine
parent: Midjourney API v2
nav_order: 800
---
## Midjourney [/imagine](https://docs.midjourney.com/docs/quick-start#5-use-the-imagine-command) command 
{: .no_toc }

<small>December 2023 (September 1, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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](../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=<code class="language-plaintext highlighter-rouge">jobid</code>](../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.

{: .post }
> **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](../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](../api-v2/get-account-midjourney) will be used. See [Setup Midjourney](../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](../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](../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 

{% tabs post_imagine_response %}

{% tab post_imagine_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve job status and results](../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](https://useapi.net/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
}
```
{% endtab %}

{% tab post_imagine_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "prompt, discord or channel value is missing"
      "prompt, replyRef or replyUrl is too long"
    "code": 400
}
```
{% endtab %}


{% tab post_imagine_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_imagine_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_imagine_response <span class="http-status-bad">422</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422" rel="noreferrer" target="_blank"><span class="http-status-bad">422 Unprocessable Content</span></a>

Moderated message or invalid prompt params, see [Midjourney moderation system](../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
}
```
{% endtab %}

{% tab post_imagine_response <span class="http-status-bad">429</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429" rel="noreferrer" target="_blank"><span class="http-status-bad">429 Too Many Requests</span></a>

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
}
```
{% endtab %}

{% tab post_imagine_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}


{% tab post_imagine_response <span class="http-status-bad">503</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503" rel="noreferrer" target="_blank"><span class="http-status-bad">503 Service Unavailable</span></a>

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
}
```
{% endtab %}

{% tab post_imagine_response <span class="http-status-bad">504</span> %}
<span class="http-status-bad">504 Job queued</span>

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
}
```
{% endtab %}

{% tab post_imagine_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs imagine_example %}

{% tab imagine_example 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": "…"}'
```
{% endtab %}

{% tab imagine_example 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});
```
{% endtab %}

{% tab imagine_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-info ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-info
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/info
parent: Midjourney API v2
nav_order: 1200
---
## Midjourney [/info](https://docs.midjourney.com/docs/info) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/info](https://docs.midjourney.com/docs/info) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](../api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](../api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_info_response %}

{% tab post_info_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_info_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_info_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_info_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_info_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_info_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs  info_example %}

{% tab  info_example 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": "…"}'
```
{% endtab %}

{% tab  info_example 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});
```
{% endtab %}

{% tab  info_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-relax ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-relax
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/relax
parent: Midjourney API v2
nav_order: 1300
---
## Midjourney [/relax](https://docs.midjourney.com/docs/fast-relax) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/relax](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](../api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](../api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_relax_response %}

{% tab post_relax_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_relax_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_relax_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_relax_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_relax_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_relax_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs  relax_example %}

{% tab  relax_example 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": "…"}'
```
{% endtab %}

{% tab  relax_example 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});
```
{% endtab %}

{% tab  relax_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-remix ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-remix
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/remix
parent: Midjourney API v2
nav_order: 1700
---
## Midjourney [/prefer remix](https://docs.midjourney.com/docs/remix) command to toggle remix mode on/off. 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/prefer remix](https://docs.midjourney.com/docs/remix) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney) will be used. See [Setup Midjourney](../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](../api-v2/get-account-midjourney).  

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_remix_response %}

{% tab post_remix_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_remix_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_remix_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_remix_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_remix_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_remix_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs  remix_example %}

{% tab  remix_example 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": "…"}'
```
{% endtab %}

{% tab  remix_example 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});
```
{% endtab %}

{% tab  remix_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-seed ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-seed
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/seed
nav_order: 1850
nav_exclude: true
---
## Retrieve the [seed](https://docs.midjourney.com/docs/seeds).<span class="required-input-field"><b>*</b></span> 
{: .no_toc }

<small>December 2023 (May 5, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---
<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](post-jobs-seed) will be routed to [jobs/seed_async](post-jobs-seed_async).  
> Please consider switching to [jobs/seed_async](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](post-jobs-imagine)
* [jobs/button](post-jobs-button)
* [jobs/blend](post-jobs-blend)

{: .post }
> **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](../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*](../api-v2/get-jobs-jobid#model)) [jobs/imagine](post-jobs-imagine), [jobs/button](post-jobs-button) or [jobs/blend](post-jobs-blend) job. 

- `discord` is optional, if provided will override `discord` value of referenced above `jobid`, see [Setup Midjourney](../start-here/setup-midjourney) for details. If the `channel` corresponding to the `jobid` mentioned above has an account configured under [account/midjourney](../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](../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 

{% tabs post_seed_response %}

{% tab post_seed_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

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
}
```

{% endtab %}

{% tab post_seed_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```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
}
```

{% endtab %}

{% tab post_seed_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
    "error": "Unauthorized",
    "code": 401
}
```
{% endtab %}

{% tab post_seed_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_seed_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
    "error": "Unable to locate parent job <jobid>",
    "code": 404
}
```
{% endtab %}

{% tab post_seed_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs seed_example %}

{% tab seed_example 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": "…"}'
```
{% endtab %}

{% tab seed_example 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});
```
{% endtab %}

{% tab seed_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-seed_async ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-seed_async
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/seed_async
parent: Midjourney API v2
nav_order: 1800
---
## Retrieve the [seed](https://docs.midjourney.com/docs/seeds).
{: .no_toc }

<small>October 7, 2024 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Retrieve the [seed](https://docs.midjourney.com/docs/seeds) and **four separate upscaled** images for the following completed jobs: 
* [jobs/imagine](post-jobs-imagine)
* [jobs/button](post-jobs-button)
* [jobs/blend](post-jobs-blend)

Please note that video generation jobs are not supported.

{: .post }
> **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](../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*](../api-v2/get-jobs-jobid#model)) [jobs/imagine](post-jobs-imagine), [jobs/button](post-jobs-button) or [jobs/blend](post-jobs-blend) job. 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_seed_async_response %}

{% tab post_seed_async_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

Use returned `jobid` to [retrieve job status and results](../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
}
```

{% endtab %}

{% tab post_seed_async_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>
```json
{
    "error": 
      "<jobid> is missing"
      "<replyRef | replyUrl> is too long"
      "Parent job must be completed"
      "Job of type <verb> not supported"
    "code": 400
}
```

{% endtab %}

{% tab post_seed_async_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>
```json
{
    "error": "Unauthorized",
    "code": 401
}
```
{% endtab %}

{% tab post_seed_async_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_seed_async_response <span class="http-status-bad">404</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404" rel="noreferrer" target="_blank"><span class="http-status-bad">404 Not Found</span></a>
```json
{
    "error": "Unable to locate parent job <jobid>",
    "code": 404
}
```
{% endtab %}

{% tab post_seed_async_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_seed_async_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}

{% endtabs %}

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

{% tabs seed_async_example %}

{% tab seed_async_example 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": "…"}'
```
{% endtab %}

{% tab seed_async_example 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});
```
{% endtab %}

{% tab seed_async_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-turbo ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-turbo
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/turbo
parent: Midjourney API v2
nav_order: 1500
---
## Midjourney [/turbo](https://docs.midjourney.com/docs/fast-relax) command 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/turbo](https://docs.midjourney.com/docs/fast-relax) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](../api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](../api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_turbo_response %}

{% tab post_turbo_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_turbo_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_turbo_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_turbo_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_turbo_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_turbo_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs turbo_example %}

{% tab  turbo_example 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": "…"}'
```
{% endtab %}

{% tab  turbo_example 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});
```
{% endtab %}

{% tab  turbo_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/post-jobs-variability ===
Document URL: https://useapi.net/docs/api-v2/post-jobs-variability
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/variability
parent: Midjourney API v2
nav_order: 1600
---
## Midjourney [/prefer variability](https://docs.midjourney.com/docs/variations) command to toggle between <small>`Vary (Strong)`</small> and <small>`Vary (Subtle)`</small> 
{: .no_toc }

<small>December 2023 (August 15, 2025)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

Use this endpoint to submit the Midjourney [/prefer variability](https://docs.midjourney.com/docs/variations) command to your [Discord Midjourney channel](../start-here/setup-midjourney#locate-midjourney-direct-messages-channel). 

{: .post }
> **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](../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](../api-v2/get-account-midjourney).   
You may specify the `channel` when you have multiple [account/midjourney](../api-v2/get-account-midjourney) accounts setup at wish to use a specific account from the configured list at [account/midjourney](../api-v2/get-account-midjourney). 

- `replyUrl` is optional, if not provided value from [useapi.net account](../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 

{% tabs post_variability_response %}

{% tab post_variability_response <span class="http-status-good">200</span> %}

<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200" rel="noreferrer" target="_blank"><span class="http-status-good">200 OK</span></a>

```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
}
```
{% endtab %}

{% tab post_variability_response <span class="http-status-bad">400</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400" rel="noreferrer" target="_blank"><span class="http-status-bad">400 Bad Request</span></a>

```json
{
    "error": 
      "discord or channel value is missing"
      "replyRef or replyUrl is too long"
    "code": 412
}
```
{% endtab %}

{% tab post_variability_response <span class="http-status-bad">401</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401" rel="noreferrer" target="_blank"><span class="http-status-bad">401 Unauthorized</span></a>

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

{% tab post_variability_response <span class="http-status-bad">402</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402" rel="noreferrer" target="_blank"><span class="http-status-bad">402 Payment Required</span></a>

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

{% tab post_variability_response <span class="http-status-bad">502</span> %}
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" rel="noreferrer" target="_blank"><span class="http-status-bad">502 Bad Gateway</span></a>

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.

{% endtab %}

{% tab post_variability_response <span class="http-status-bad">596</span> %}
<span class="http-status-bad">596 Pending mod message</span>

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](../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
}
```
{% endtab %}


{% endtabs %}

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

{% tabs  variability_example %}

{% tab  variability_example 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": "…"}'
```
{% endtab %}

{% tab  variability_example 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});
```
{% endtab %}

{% tab  variability_example 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())
```
{% endtab %}

{% endtabs %}


=== URL: https://useapi.net/docs/api-v2/setup-multiple-midjourney-accounts ===
Document URL: https://useapi.net/docs/api-v2/setup-multiple-midjourney-accounts
---
layout: default
title: ⚙️ Setup multiple accounts
parent: Midjourney API v2
nav_order: 4000
---
## How to use multiple Midjourney accounts 
{: .no_toc }

<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](../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](../start-here/setup-midjourney).
- Post your configuration(s) using the [account/midjourney](../api-v2/post-account-midjourney) endpoint.

To see all your currently configured Midjourney accounts, please use the [account/midjourney](../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](../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
---
layout: default
title: 🖌️ Vary Region mask editor
parent: Midjourney API v2
nav_order: 3000
---
## Simple Vary Region (inpaint) mask editor
{: .no_toc }

<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](../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>


=== URL: https://useapi.net/docs/questions-and-answers ===
Document URL: https://useapi.net/docs/questions-and-answers
---
title: Q&A
nav_order: 110000
layout: home
---

# Questions and Answers
{: .no_toc }

<small>4 min read • September 2023 (January 14, 2026)</small>

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

### How to avoid Midjourney bans?  

Using automation is against Discord and Midjourney's Terms of Service, so you need to plan accordingly and have backup account(s) ready. 

* The best practice is to create several new Discord accounts and join the Midjourney Discord server. These accounts should be used exclusively for API work and nothing else. We strongly recommend using a VPN to prevent your personal data/IP addresses from being leaked. You can use the [Opera](https://www.opera.com/download) browser with built-in VPN or the [Brave](https://brave.com/download) browser with [Tor support](https://support.brave.com/hc/en-us/articles/360018121491-What-is-a-Private-Window-with-Tor-Connectivity).

* Brand new/fresh Discord accounts have a significantly 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 appear more legitimate and are less likely to trigger automated bans.

* When creating accounts in bulk, make sure to restart Opera/Brave so that your IP is different every time, since Discord tracks and records the IP addresses used to create new accounts. Make sure to log in to the Discord accounts designated for API use through a VPN. When creating new email and Discord accounts, use names closely resembling real names - something that does not look suspicious.

* Once a Discord account is created, join the Midjourney Discord [server](https://discord.com/invite/midjourney) and follow the [instructions](https://useapi.net/docs/start-here/setup-midjourney) to create your own server and invite the Midjourney bot. If you're planning to use this account, you can proceed with a Midjourney subscription. It's a good idea to create several Discord accounts with the Midjourney setup, as described above early on, this will *"age"* them and make them less suspicious later on when you need to subscribe to Midjourney.

* When paying for a Midjourney subscription use a virtual credit card number (provided by most major credit card companies) or services like [Privacy.com](https://privacy.com). Make sure to use a credit card name and address that resemble an actual address and name. Use a *different name and address* for every new Midjourney subscription. Midjourney has access to all payment details and will cross-check banned accounts' payment information to ban newly created accounts if a match is found.

* If your account gets banned, file a charge dispute with your credit card company. Since Midjourney cannot produce any evidence of you violating the ToS, the bank will fully refund your payment. Our customers have reported a 100% success rate of getting their money back, though it may take some time.

* When using the API, try to simulate real users. Avoid running generations 24/7 by establishing quiet hours (for example, you can use two or three accounts and rotate them every 12/8 hours). Midjourney seems to specifically target accounts with a large number of `--relax` usage, so try to limit those generations to a reasonable number (<300 generations/day). If you heavily rely on `--relax`, execute at least one fast generation for every NN relax generations. 
  
* Do not post public links to Discord/Midjourney CDN attachments, they contain your Discord account number and can be used to trace back to your account.

* Sharing cross-account `--p` codes is not safe. You risk all accounts using the same `--p` codes being banned by Midjourney.

* Do not run multiple requests with the same or similar prompts (e.g., "My test prompt 1", "My test prompt 2", and so on). Midjourney analyzes prompts and will force your Discord account token to expire when this kind of situation is detected. You will have to reset your Discord password manually before you can continue operating.

* Adjust [maxJobs](../docs/api-v2/post-account-midjourney) parameter to be one less than the maximum possible. For example, for the [Pro Plan](https://docs.midjourney.com/docs/plans) with a maximum of 12 concurrent jobs, set `maxJobs` to 11 or even 10.

* If you ever receive a [504](../docs/api-v2/post-jobs-imagine#responses) response code, it means your `maxJobs` is set to a value higher than your account plan supports. Adjust it accordingly.

* Finally, monitor for [596](../docs/api-v2/post-jobs-imagine#responses) response codes and ensure you check your API email. The API will proactively warn you if you have pending moderation messages or if Midjourney issues a CAPTCHA request.

### How to avoid Runway account suspension?

Using automation is against Runway's Terms of Service, so you need to plan accordingly and have backup account(s) ready.

* The best practice is to create several stand-by Runway accounts. These accounts should be used exclusively for API work and nothing else. We strongly recommend using a VPN to prevent your personal data/IP addresses from being leaked. You can use the [Opera](https://www.opera.com/download) browser with a built-in VPN or the [Brave](https://brave.com/download) browser with [Tor support](https://support.brave.com/hc/en-us/articles/360018121491-What-is-a-Private-Window-with-Tor-Connectivity).

* When creating accounts in bulk, make sure to restart Opera/Brave so that your IP is different every time. When creating new emails and Runway accounts, use names that closely resemble real names—something that does not look suspicious.

* Once a new Runway account is created, you will have a few free credits with which you can test the API. After testing, log out and leave the account alone until you are ready to activate the [Unlimited plan](https://runwayml.com/pricing) (the only subscription plan that makes sense to pay for).

* When paying for a Runway subscription, use a virtual credit card number (provided by most major credit card companies) or services like [Privacy.com](https://privacy.com). Make sure to use a credit card name and address that resemble an actual name and address. Use a *different name and address* for every new Runway subscription. Runway has access to all payment details and can cross-check banned accounts' payment information to ban newly created accounts if a match is found.

* If your account gets suspended, file a charge dispute with your credit card company. Since Runway cannot produce any evidence of you violating the ToS, the bank will fully refund your payment. Our customers have reported a 100% success rate of getting their money back, though it may take some time.

* When using the API, try to simulate real users. Avoid running generations 24/7 by establishing quiet hours (for example, you can use two or three accounts and rotate them every 12 to 8 hours). Avoid calling API endpoints too frequently, and consider using the `replyUrl` webhook to retrieve results, as this will ensure the least intrusive operation.

* Finally, monitor your API email—the one you used to subscribe to useapi.net services. The API will proactively warn you if your Runway account has any issues.

### Do you validate a user's text/image prompts to ensure they are passing AI services' safety requirements?

It is common practice for AI services to ban users for violating prompt guidelines (for example, see Midjourney PG13 [requirements](https://docs.midjourney.com/docs/community-guidelines)). Our API does not perform any prompt pre-validations, it will return a [422](../docs/api-v2/post-jobs-imagine#responses) status code if the job is moderated by Midjourney, and similar checks apply for the other AI APIs we offer.

Generally speaking, if you're planning to use the API for a public Telegram bot (which is one of the popular use cases) or in similar scenarios where you do not control the quality of the prompt, it might be a good idea to use a combination of a ban/stop word list along with [OpenAI ChatGPT](https://openai.com/api/pricing) or [Google Gemini](https://ai.google.dev/pricing) to check if the prompts meet safety requirements. [Gemini](https://ai.google.dev/pricing) offers a free tier with some RPM (requests per minute) limitations.

We also offer LLM models, specifically `MiniMax-Text-01`, a fast instructional multimodal model that is free to use and can validate both text and images for safety. Please see [POST minimax/llm](../docs/api-minimax-v1/post-minimax-llm).

### How is your experimental Runway API different from the official Runway API?

Official [Runway API](https://docs.dev.runwayml.com) currently only supports Gen-3 Alpha Turbo. The cost for Gen-3 Alpha Turbo 10-second generation is [$0.50](https://docs.dev.runwayml.com/usage/billing).

Our [experimental Runway API](https://useapi.net/docs/api-runwayml-v1) is a reverse-engineered version of [runwayml.com](https://runwayml.com). It fully supports **all** features of Gen-3 Alpha, Gen-3 Alpha Turbo, Act-One, Video to Video, Super-Slow Motion, Gen-2, the LipSync feature, and [more](https://useapi.net/docs/api-runwayml-v1). When used along with the Runway [Unlimited plan](https://runwayml.com/pricing), it allows you to run several hundred generations each day.

On average, you can expect the following numbers for Gen-3 Alpha Turbo 10-second generation:
- 1 generation is completed within 25 seconds
- 10 generations take about 4 minutes to complete
- 30 generations take about 12 minutes to complete
- 150 generations take about one hour to complete
    
If you generate 200+ videos, the official API will cost you $0.50 per generation, so 200 generations cost about $100. This means the $95 [Unlimited plan](https://runwayml.com/pricing), combined with our $15/month subscription, will pay for itself by the **first day**, most often within the first few hours.

We provide an API for all the features available at [runwayml.com](https://runwayml.com), including Gen-3 Alpha, Act-One, video-to-video (with extend and expand), Frames, and many more. The official Runway API only supports [Gen-3 Alpha Turbo](https://docs.dev.runwayml.com/).

### How is your experimental MiniMax API different from the official MiniMax API?

Official [MiniMax API](https://intl.minimaxi.com/document/video_generation) costs $0.43…$0.65 [link](https://www.minimaxi.com/en/price) per single 6-second-long generation.

Our [experimental MiniMax API](https://useapi.net/docs/api-minimax-v1) is a reverse-engineered version of the MiniMax/HailuoAI websites. It does not cost you anything to generate as many videos as you wish, thanks to a flat monthly [subscription](https://useapi.net/docs/subscription) fee. You can link as many [paid](https://hailuoai.video/subscribe) or free MiniMax/HailuoAI accounts to our API as you wish.

With [Unlimited](https://hailuoai.video/subscribe) Hailuo AI plan or [Standard](https://hailuoai.video/subscribe) plan for first day, you can expect the following numbers:
- 1 generation completed within 2 minutes
- 10 generations take about 20 minutes to complete
- 30 generations take about an hour to complete

If you generate 250+ videos, the official API will cost you $0.43 per generation, so 250 generations total about $107.50. This means the $95 [Unlimited](https://hailuoai.video/subscribe) plan, combined with our $15/month subscription, will pay for itself by the **first day**.

When using free [hailuoai.video](https://hailuoai.video) account, it costs one credit to generate a single image, and you can generate up to four images at once. With a daily free top-up of 100 credits, a free hailuoai.video account can generate 100 images per day – up to 3K images per month.

### Do you support [n8n](https://n8n.io) workflow automation?

Please consider the [n8n-nodes-useapi](https://github.com/lvalics/n8n-nodes-useapi) package by [lvalics](https://github.com/lvalics).

### How POST raw content to [runwayml/assets](https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets) and [minimax/files](https://useapi.net/docs/api-minimax-v1/post-minimax-files) using Make.com and similar nocode tools?

We recommend using module called [0codekit](https://www.make.com/en/integrations/onesaas) to run JavaScript and return a result. 

<details markdown="block">

<summary><small>0codekit JavaScript example</small></summary>

```js
async function fetchFromURLandPOST(imageURL, name) {
  const apiToken = "<Your useapi.net API key>"; // https://useapi.net/docs/start-here/setup-useapi
  // Runway https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets
  const apiUrl = `https://api.useapi.net/v1/runwayml/assets/?name=${name}`;
  // MiniMax https://useapi.net/docs/api-minimax-v1/post-minimax-files
  // const apiUrl = `https://api.useapi.net/v1/minimax/files/`;

  try {
    // Fetch the image from the URL
    const responseImage = await fetch(imageURL);

    if (!responseImage.ok) 
      throw new Error(`Failed to fetch ${imageURL}: ${responseImage.statusText}`);

    // Convert the response to a Blob
    const blob = await responseImage.blob();

    // Prepare headers for the POST request
    const headers = {
      "Authorization": `Bearer ${apiToken}`, 
      "Content-Type": blob.type,
    };

    // Make the POST request with the blob as the body
    const response = await fetch(apiUrl, {
      method: "POST",
      headers: headers,
      body: blob,
    });

    const result = await response.json();
    return { data: result };
  } catch (error) {
    return { error: error.message };
  }
}

// Calling the function
result = await fetchFromURLandPOST("https:\\website.com\image.jpeg", "my_image");
```

</details>