POST pixverse/button

PixVerse button command

Request Headers
Request Body
Responses
Model
Examples
Try It

Use this endpoint to submit the PixVerse button command to your Discord PixVerse channel. Results obtained as a callback via optional parameter replyUrl or by querying pixverse/jobs/?jobid=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.

https://api.useapi.net/v1/pixverse/button

Request Headers

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 for details.

Request Body

{
    "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 pixverse/create, pixverse/animate, pixverse/create_single, pixverse/meme_face or pixverse/button job.
button is required, button from buttons array of job referenced via jobid above, see button.
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 for details. If the channel corresponding to the jobid mentioned above has an account configured under 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 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 to test callback URL functionality.
replyRef is optional, place here your reference id which will be stored and returned along with this job response / result.
Maximum length 1024 characters.

Responses

200 OK

Use returned jobid to retrieve PixVerse job status and results. content contains message generated by PixVerse reflecting current generation parameters and progress.

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

400 Bad Request

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

401 Unauthorized

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

402 Payment Required

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

429 Too Many Requests

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

There are two possible cases for API response 429.
1. API query is full and can not accept new pixverse/button requests. Size of query defined by maxJobs optional parameter. Wait in a loop for at least 10..30 seconds and retry again.
```
{
 "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.
```
{
 "error": "Discord /interactions failed with HTTP status 429",
 "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}",
 "code": 429
}
```

Model

{ // 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

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

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()

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())