Introduction

Welcome to the AIMG Back-End API documentation. The following endpoints control the AIMG Worker.

API Endpoints

The {BaseURL} for the API endpoints depends on the originating domain:

Sexy.ai: https://api.sexy.ai
FreeJourney.ai: https://api.freejourney.ai
Sexy.ai (Staging): https://staging-api.sexy.ai
FreeJourney.ai (Staging): https://staging-api.freejourney.ai

Unless specified otherwise, all API calls will return an application/json response.

All requests require a X-Session-ID header, which must be a valid UUID. This header is used to identify the User making the request, as well as to ensure that the User is logged in, and to track their activity.

Pagination

Some API endpoints support pagination. Please, refer to the Annex: Pagination section for more information.

The API server supports the following OAuth 2.0 (RFC 6749) login providers as an alternative to logging in with the native workflow:

Google
Discord
GitHub

All login providers work in the same way, but are triggered by different endpoints. The different login providers will automatically fetch the email (and a username, where available) of the User from the external provider and create an internal User with the same email if such User does not exist. Logins through external providers support User account idempotency as long as they are linked to the same email address.

Upon triggering the request URL, the User will be redirected through a HTTP Code 302 (Temporary Redirect) to the login page of the external provider. After a successful login, the API server will return the information about the User to the front-end website through the redirection URL specified in the request, formatted as a Base64URL (RFC 4648) encoded JSON object, passed as a query parameter (application/x-www-form-urlencoded-like).

This endpoint supports a application/x-www-form-urlencoded payload, and must be called as a form button. The user will be redirected to redirectURL afterwards.

HTTP Request

POST {BaseURL}/auth/{loginProvider}

Path Parameters

Parameter	Type	M/O	Description
loginProvider	string	M	The OAuth 2.0 login provider. Supported values are: `google`, `discord`, `github`.

Body Parameters

Parameter	Type	M/O	Description
redirectURL	string	M	The front-end website URL where the User information will be returned after login. It is suggested to URL-encode it.
refList	string	O	An comma-separated list of browser referrers.
rs	string	O	An affiliate referrer for the User. Used to track who referred the User.
isAtLeast18Confirmed	boolean	O	Whether the User has confirmed being 18+ years old.

HTTP Response

The response is passed to the front-end website as a Base64URL (RFC 4648) encoded JSON object, passed as query parameter.

Parameter	Type	M/O	Description
b	string	M	Base64URL encoded JSON object representing the response body.

When decoded, the response body contains the payload object, corresponding to a SelfUser object.

User Management

Create User

This endpoint creates a User on the website by their email, given their One-Time Password (OTP) or chosen password.

If the X-Session-ID header is not provided, a new session ID will be created for the User and returned in the response body.

At least one of the following properties must be provided: password, otp.

When password is provided, it must satisfy the following requirements:

Must be at least 8 characters long. No limitation on the maximum length of the password is applied in the back-end, front-ends may impose their own limits.
Must contain at least one uppercase character ([A-Z]).
Must contain at least one lowercase character ([a-z]).
Must contain at least one numeric character ([0-9]).
Must contain at least one special character ([!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]).

The full RegExp to enforce password requirements at the front-end is: ^(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]).{8,}$.

HTTP Request

POST {BaseURL}/createUser

Body Parameters

Parameter	Type	M/O	Description
email	string	M	The email of the User.
username	string	O	The chosen username of the User.
password	string	O	The chosen password of the User.
otp	string	O	The One-Time Password (OTP) provided to the User via email.
isAtLeast18Confirmed	boolean	O	Whether the User has confirmed being 18+ years old.
refList	string[]	O	An array of referees of browser referrers.
rs	string	O	An affiliate referrer for the User. Used to track who referred the User.

HTTP Response

The response contains the payload object, corresponding to a SelfUser object.

Authenticate User

This endpoint autenticates an already registered User, returning the information about them. If the User is not registered, it will be created automatically.

At least one of the following properties must be provided: password, otp.

HTTP Request

POST {BaseURL}/authenticateUser

Body Parameters

Parameter	Type	M/O	Description
email	string	M	The email of the User.
password	string	O	The chosen password of the User.
otp	string	M	The One-Time Password (OTP) provided to the User via email.
isAtLeast18Confirmed	boolean	O	Whether the User has confirmed being 18+ years old.

HTTP Response

The response contains the payload object, corresponding to a SelfUser object.

Sign Out User

This endpoint signs out the currently logged User, clearing their session and revoking any OAuth token linked to the current session (if available).

HTTP Request

POST {BaseURL}/signOutUser

Body Parameters

None.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the User's session was successfully deleted. If `false`, the User session did not exist to begin with.
message	string	An additional message that may be displayed on the front-end.

Request OTP Code for User

This endpoint triggers an email being sent to the User, containing their One-Time Password (OTP).

An OTP can only be used once and is valid for 24 hours since its creation.

The email will also contain a "magic link" that can be used to login directly from the front-end, without having to insert the OTP. The "magic link" feature is only available if the front-end is configured to allow it. The "magic link" will contain a JSON object with the email and otp parameters needed to call the authenticateUser endpoint (toghether with the X-Session-ID header of the current front-end session), in the form of a Base64URL (RFC 4648) encoded JSON object, passed as query parameter b.

Example query parameter b:

b=eyJlbWFpbCI6ImFAYi5jb20iLCJvdHAiOiIxMjM0NTYifQ

where the JSON object is:

{"email":"[email protected]","otp":"123456"}

HTTP Request

POST {BaseURL}/requestOTP

Body Parameters

Parameter	Type	M/O	Description
email	string	M	The email of the User.
signUp	boolean	O	Whether the User is signing up. This must be `true` if the User is signing up to allow for specific errors to be returned.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the OTP was successfully sent to the User.
message	string	An additional message that may be displayed on the front-end.

Get Self User

This endpoint returns the information about the currently logged User.

Parameter isAtLeast18Confirmed is optional and not required to obtain the User information. If provided, the back-end will remember whether the User has confirmed being 18+ years old.

If the X-Session-ID header is not provided, a new session ID will be created for the User and returned in the response body.

HTTP Request

GET {BaseURL}/getSelfUser

Query Parameters

Parameter	Type	M/O	Description
isAtLeast18Confirmed	boolean	O	Whether the User has confirmed being 18+ years old.
profilePicture	boolean	O	Whether to return the profile picture of the User.
extendedPriceInfo	boolean	O	Whether to return the pricing information about the User's subscription plans.

HTTP Response

The response contains the payload object, corresponding to a SelfUser object.

Set Self User Properties

This endpoint sets properties for the currently logged User (e.g., modifying the username, email, password, etc.).

At least one of the User properties must be provided.

In order to change a User's email using the email parameter, a valid OTP must be provided. The OTP must be requested via the requestOTP endpoint, using the target email in the email parameter, with the signUp parameter set to true.

Attempting to change the email under the following conditions will result in an error:

The User has logged in with an external login provider at least once with the current email.
The User PRO tier is higher than 0.
The User has a subscription through a Merchant Processor.
The provided OTP is invalid, or not provided at all.
The target email is not a valid email address.
The target email is already in use, or it's the same as the current email.

When password is provided, it must satisfy the following requirements:

Must be at least 8 characters long. No limitation on the maximum length of the password is applied in the back-end, front-ends may impose their own limits.
Must contain at least one uppercase character ([A-Z]).
Must contain at least one lowercase character ([a-z]).
Must contain at least one numeric character ([0-9]).
Must contain at least one special character ([!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]).

The full RegExp to enforce password requirements at the front-end is: ^(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]).{8,}$.

Changing the password will invalidate all User sessions except the current one.

HTTP Request

POST {BaseURL}/setSelfUserProperties

Body Parameters

Parameter	Type	M/O	Description
username	string	O	The chosen username of the User.
password	string	O	The chosen password of the User.
email	string	O	The chosen email of the User.
otp	string	O	The One-Time Password requested by the User. Mandatory if attempting to change the email address.
isAtLeast18Confirmed	boolean	O	Whether the User has confirmed being 18+ years old.

HTTP Response

The response contains the payload object, corresponding to a SelfUser object.

Set Self User Profile Picture

This endpoint sets the profile picture of the currently logged User. The Profile Picture must be passed as a base64 Data URI encoded payload directly into the request body. It is up to the front-end to fetch the Profile Picture from the User (e.g., via an URL or an upload field) and to encode the payload accordingly.

Here are the supported image formats:

the Profile Picture must have one of the following MIME types: image/jpeg, image/jpg, image/png, image/tiff, image/webp.
the maximum size of the Profile Picture is 1 MB.
the maximum resolution of the Profile Picture is 1024x1024 px.

The Profile Picture will be compressed and normalized to image/webp format with a resolution of 128x128 px, and the corresponding Data URI payload will be returned in the response.

In order to remove the Profile Picture of the User, the profilePicture parameter must be set to an empty string ("") in the request body.

HTTP Request

POST {BaseURL}/setSelfUserProfilePicture

Body Parameters

Parameter	Type	M/O	Description
profilePicture	string	M	The Profile Picture encoded payload, as a base64 Data URI.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
profilePicture	string	The Profile Picture of the User, returned as base64 Data URI.

Set Profile Picture Banned

This endpoint sets the banned status of the profile picture of a User. When banned, the User will not be able to change their profile picture.

The banned status can be set to true or false. When the banned status is set to true, the profile picture for the User will be removed. The profile picture will not be restored when the banned status is set to false.

The current banned status will be returned in the response after a successful change, or if the request is done without specifying the banned status.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/setProfilePictureBanned

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User. At least one between `userID` and `email` must be passed in the request.
email	string	O	The email of the User. At least one between `userID` and `email` must be passed in the request.
profilePictureBanned	boolean	O	The banned status of the profile picture of the User. If not provided, the current banned status will be returned.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
profilePictureBanned	boolean	Whether the profile picture of the User is banned.

Set User Additional Information

This endpoint sets the the additional information field of a User, which can be used to store notes about the User.

The current additional information will be returned in the response after a successful change.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/setUserAdditionalInformation

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User. At least one between `userID` and `email` must be passed in the request.
email	string	O	The email of the User. At least one between `userID` and `email` must be passed in the request.
additionalInformation	string	O	The additional information of the User. If not provided, or empty, the current additional information will be removed.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
additionalInformation	string	The additional information of the User.

Get User Key-Value Pair

This endpoint returns a value for the currently logged User, given its key.

HTTP Request

GET {BaseURL}/getUserKVP

Query Parameters

Parameter	Type	M/O	Description
key	string	M	The key of the User Key-Value Pair.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
key	string	The key of the User Key-Value Pair.
value	string	The value of the User Key-Value Pair.

Set User Key-Value Pair

This endpoint sets a custom value for the currently logged User, attaching it to a provided key.

HTTP Request

POST {BaseURL}/setUserKVP

Body Parameters

Parameter	Type	M/O	Description
key	string	M	The key of the User Key-Value Pair.
value	string	M	The value of the User Key-Value Pair.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
key	string	The key of the User Key-Value Pair.
value	string	The value of the User Key-Value Pair.

Delete User Key-Value Pair

This endpoint deletes a previously set value for the currently logged User, given its key.

HTTP Request

DELETE {BaseURL}/deleteUserKVP

Query Parameters

Parameter	Type	M/O	Description
key	string	M	The key of the User Key-Value Pair.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the User Key-Value Pair was successfully deleted.

Get User

This endpoint returns information about a User.

When used by Admins, extended information about the User will be returned, and will also return information about deleted Users. Additionally, Admins can look Users up by their email address and username, while Users can only look up a User by their identifier.

HTTP Request

GET {BaseURL}/getUser

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	O	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User. Mandatory if the `X-Administration-Key` header is not provided.
email	string	O	The email of the User. Email lookup is only available if the `X-Administration-Key` header is provided. At least one of `userID`, `email` or `username` must be provided.
username	string	O	The username of the User. Username lookup is only available if the `X-Administration-Key` header is provided. At least one of `userID`, `email` or `username` must be provided.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
userID	string	The unique identifier of the User.
username	string	The chosen username of the User.
profilePicture	string	The Profile Picture of the User, returned as base64 Data URI.

Additionally, when used by Admins, extended information will be returned:

Parameter	Type	Description
email	string	The email of the User.
createdDate	string	The creation date of the User, as ISO 8601 string.
updatedDate	string	The last update date of the User, as ISO 8601 string.
deletedDate	string	The deletion date of the User, as ISO 8601 string.
isDisabled	boolean	Whether the User is deleted.
isAtLeast18Confirmed	boolean	Whether the User has confirmed being 18+ years old.
tier	number	The User PRO tier.
tierExpiration	string	The timestamp (as ISO 8601 string) of when the User's tier will expire.
merchantProcessor	string	The merchant processor that generated the PRO status.
subscriptions	Subscription[]	The list of PRO subscriptions of the User.
flaggedImagesCount	number	The number of flagged images of the User.
highHeatImagesCount	number	The number of high-heat images of the User.
refList	string[]	An array of referees of browser referrers.
rs	string	An affiliate referrer for the User. Used to track who referred the User.
loginProviders	LoginProvider[]	The User's login providers.
connectProviders	LoginProvider[]	The User's connected providers.
abuse	number	Whether the User is flagged as abusive.
profilePicture	boolean	Whether the User has a Profile Picture set.
profilePictureBanned	boolean	Whether the profile picture of the User is banned.
archivedEmails	ArchivedEmail[]	The User's archived emails.
itemCount	number	The number of Items owned by the User.
publicItemCount	number	The number of items in the User's public folders.
rootFolderItemCount	number	The number of Items owned by the User and contained in the root Folder.
additionalInformation	string	The additional information of the User.
roles	string[]	The roles of the User.

Generate a Strong Password

This endpoint generates a strong password that satisfies the password requirements. This is a helper endpoint for the front-end.

HTTP Request

GET {BaseURL}/generateStrongPassword

HTTP Response

The response contains the payload object, corresponding to the generated password.

Delete User

This endpoint deletes the currently logged User.

When used by Admins, any User can be targeted by specifying the userID parameter.

it will also show the possible system report queues (queues that are automatically created by the system based on internal parameters) to be used in the Get Reports endpoint. Otherwise, it will only show the report queues that can be used by the User through the Report Items endpoint.

HTTP Request

DELETE {BaseURL}/deleteUser

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	O	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User. Only accounted for if the endpoint is called by an Admin.
deleteItems	boolean	O	Whether to delete the User's Items as well.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the User was successfully deleted.

Set User Abuse Level

This endpoint sets the abuse level of a User.

Abuse level can be set as any integer between 0 and 9. Each level will apply different limits to the User, with each level including the limits from the previous levels.

The currently supported abuse levels are:

0: No limits.
1: Item Generation is blocked (both image and video generation, both from the old and new AI generation workflows).
9: The User is immediately kicked out of any existing session, and will not be able to log in again. Any existing subscriptions will not be canceled.

Using the endpoint with no level (or with an invalid level) will return the current abuse level of the User.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/setUserAbuseLevel

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User. At least one of `userID` or `email` must be provided.
email	string	O	The email of the User. At least one of `userID` or `email` must be provided.
abuse	number	O	The new abuse level.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
abuse	number	The new or current abuse level of the User.

Premium Membership Management

Get Billing Plans

This endpoint provides the User with the information about the available Billing Plans.

HTTP Request

GET {BaseURL}/getBillingPlans

Query Parameters

Parameter	Type	M/O	Description
redirectURL	string	O	The URL to redirect the User to once they have finished buying a Billing Plan. Generally optional, but required for some payment processors (e.g., PayPal). It is suggested to URL-encode it.
paymentURL	string	O	The URL to redirect the User to process a payment through the self-hosted payment page. Generally optional, but required for some payment processors (e.g., ArkPay). It is suggested to URL-encode it.
planIDs	string	O	A comma-separated list of identifiers of the Billing Plans. Used to filter results and return only the specified Plans.
code	string	O	A code used to show specific special plans (e.g. a coupon code).

HTTP Response

The response contains the payload object, corresponding to an array of BillingPlan objects.

Create Billing Plan

This endpoint adds a new Billing Plan to the list of available Billing Plans.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/createBillingPlan

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
name	string	M	The name of the new Billing Plan.
description	string	O	The description of the new Billing Plan.
features	string[]	O	An array of features of the new Billing Plan.
mainBenefits	string[]	O	The main benefits of the new Billing Plan.
prices	BillingPlanPrice[]	M	The available prices for the new Billing Plan.
tier	number	M	The target tier of the new Billing Plan.
env	string	O	The environment of the new Billing Plan. If not provided, the current environment is used.

HTTP Response

The response contains the payload object, corresponding to a BillingPlan object.

Cancel Membership

This endpoint provides the User with the information to cancel their current membership subscription.

For payment providers where this is supported, this endpoint sets the expiration date of the User's current subscription to the next billing cycle.

HTTP Request

DELETE {BaseURL}/cancelMembership

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the User subscription was successfully deleted, or the email with the instructions was sent.
message	string	An additional message that may be displayed on the front-end.

Process Credit Card Payment

This endpoint processes the User's credit card payment for their membership.

This endpoint supports a application/x-www-form-urlencoded payload, and must be called as a form button. The user will be redirected to redirectURL afterwards.

HTTP Request

POST {BaseURL}/processCardSubscription

Body Parameters

Parameter	Type	M/O	Description
merchantProcessor	string	M	The merchant processor to use for the payment. Possible values: `arkpay`.
productID	string	M	The identifier of the product related to the Billing Plan to which the User wants to subscribe.
cardNumber	string	M	The credit card number.
cardHolderName	string	M	The name of the credit card holder.
expirationMonth	number	M	The expiration month of the credit card.
expirationYear	number	M	The expiration year of the credit card.
securityCode	string	M	The credit card security code (CVV/CVC).
street	string	O	The street of the billing address.
city	string	O	The city of the billing address.
stateOrProvince	string	O	The state or province of the billing address. This must be a 2-letter code.
postalCode	string	O	The postal code of the billing address.
country	string	O	The country of the billing address. This must be a valid ISO 3166-1 alpha-2 code.
billingEmail	string	O	The email address associated with the credit card. If the User is logged in and the email is known, this should not be provided.
phoneNumber	string	O	The phone number associated with the credit card.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the User subscription payment was successfully processed.
message	string	An additional message that may be displayed on the front-end.

Set Admin-Provided Premium Tier

This endpoint sets a free, admin-provided Premium Tier for a User.

This endpoint can only be used by Admins.

HTTP Request

POST {BaseURL}/setAdminProvidedPremiumTier

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
productId	string	M	The identifier of the product that identifies the admin-provided Premium Tier.
email	string	O	The email of the User. At least one between `email` and `emails` must be provided.
emails	string[]	O	A list of emails of the Users that should be assigned the Premium Tier. The same settings will apply to all the Users in this list. At least one between `email` and `emails` must be provided.
tier	number	M	The tier of the Premium Tier.
isActive	boolean	M	Whether the Premium Tier should be active.
deactivationDate	string	O	The date when the Premium Tier should be deactivated. It must be provided as an ISO 8601 string.
additionalInformation	string	O	Additional information about the Premium Tier.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
_id	string	The identifier of the new Premium Tier. It will not be provided if `emails` is provided in the request.
domain	string	The domain identifier of the new Premium Tier.
paymentProvider	string	The payment provider of the new Premium Tier. This is always `admin`.
productId	string	The identifier of the product that identifies the admin-provided Premium Tier.
email	string	The email of the User, if `email` is provided in the request.
emails	string	A list of emails of the Users that were assigned the Premium Tier, if `emails` is provided in the request.
tier	number	The tier of the Premium Tier.
isActive	boolean	Whether the Premium Tier is active.
createdDate	string	The date when the new Premium Tier was created, as an ISO 8601 string.
updatedDate	string	The date when the new Premium Tier was updated, as an ISO 8601 string.
deactivationDate	string	The date when the new Premium Tier was deactivated, as an ISO 8601 string.
env	string	The environment of the new Premium Tier.
additionalInformation	string	Additional information about the new Premium Tier.

Trigger Pay With Card Email

This endpoint triggers an email being sent to the User with instructions on how to pay for their membership with their credit card.

HTTP Request

POST {BaseURL}/payWithCardEmail

Body Parameters

Parameter	Type	M/O	Description
email	string	O	The email of the User. It must be provided if the User is not logged in.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the email was successfully sent.

This endpoint allows for the injection of the Boosty Admin account cookie. This is needed for the Boosty integration to work. Each cookie, once created, expires after 7 days.

This endpoint can currently only be used by Admins.

In order to get the cookie, follow these instructions:

Using a PC or Mac, download the "Cookie Editor" extension for your browser. We recommend using Chrome or Firefox, as Safari version does NOT work properly at the moment.
Navigate to boosty.to in your browser.
If you are already logged in, logout before proceeding so that the old cookies are cleared.
Login to the Admin account using whatever credentials/login provider.
Press the Cookie Editor icon in the top right corner of the page.
The first time, Cookie Editor will warn you that "You do not have the permission required to read the cookies for this page." and ask you to "Request permission for...". Clicking on "This site" will be enough. A popup will appear in the top right corner of the page (it may be hidden by the Cookie Editor popup) and ask you to Allow the extension.
Press the "Export" button (bottom right) and select "Export As: JSON".
Cookies are now copied to your clipboard. Paste the resulting JSON (it will be an array of objects) into the cookies parameter of this endpoint.

HTTP Request

POST {BaseURL}/injectBoostyAdminAccountCookies

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
accountId	string	M	The ID of the Admin account (the ID in the URL, e.g. `sexyai`).
domainIdentifier	string	O	The identifier of the domain we want to inject cookies for (e.g. `sexy.ai`). If not provided, the current domain is used (defined by the API endpoint being used).
cookies	any[]	M	The cookie(s) in JSON format, as gathered from the exported cookies using the instructions above.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the cookies were successfully injected.

Redeem Gift Card

This endpoint redeems a Gift Card, assigning the corresponding Premium Tier to the User, for the defined duration.

A Gift Card can only be redeemed once. A Gift Card can be redeemed by any User, regardless of whether they bought it or not.

A User must be logged in to redeem a Gift Card. A User cannot redeem a Gift Card if they have an active Premium Tier which is equal to or greater than the tier of the Gift Card, unless the current tier is enqueued for expiration.

Only in such cases where the Gift Card tier is the same as the expiring Premium Tier, the Gift Card tier expiration is recalculated so that it extends the duration of the existing expiring Premium Tier.

HTTP Request

POST {BaseURL}/redeemGiftCard

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
code	string	M	The code of the Gift Card.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
productID	string	The Gift Card's product identifier, corresponding to the code of the Gift Card.
tier	number	The tier assigned to the User upon redemption of the Gift Card.
tierExpiration	string	The timestamp (as ISO 8601 string) of when the User's tier will expire.

Download Gift Cards

This endpoint downloads a list of newly created Gift Cards, according to the parameters provided.

This endpoint can currently only be used by Admins.

HTTP Request

GET {BaseURL}/downloadGiftCards

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
distributionProvider	string	O	The name of the distribution (payment) provider. Possible values: `g2a`, `giftcard`. If not provided, defaults to `giftcard`.
tier	number	O	The tier assigned to the User upon redemption of the Gift Cards. If not provided, defaults to `1`.
days	number	O	The number of days the Premium Tier should be active for upon redemption of the Gift Cards. If not provided, defaults to `30`.
numberOfCards	number	O	The number of Gift Cards to create. If not provided, defaults to `100`.
usdPrice	number	O	The USD price of the Gift Card. If not provided, defaults to `0`.
externalCodes	string	O	A comma-separated list of external code(s) of the Gift Cards. If not provided, defaults to none.
additionalInformation	string	O	Additional information about the Gift Cards.

HTTP Response

This endpoint does not return any response. It downloads the gift cards as a TXT file.

Image Management

Get Item

This endpoint returns basic information about an Item.

HTTP Request

GET {BaseURL}/getItem

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the Item.

HTTP Response

The response contains the payload object, corresponding to a Image object.

Get Item Details

This endpoint returns detailed information about an Item.

HTTP Request

GET {BaseURL}/getItemDetails

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the Item.

HTTP Response

The response contains the payload object, corresponding to a ImageInfo object.

Get Last Completed Item

This endpoint returns basic information about the last completed Item.

HTTP Request

GET {BaseURL}/getLastCompletedItem

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
mtype	string	O	The type of the Item. It can be `image` or `video`. If not specified, it defaults to both.

HTTP Response

The response contains the payload object, corresponding to a Image object.

Get My Creations

This endpoint returns a list of Items owned by the User.

HTTP Request

GET {BaseURL}/getMyCreations

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
mtype	string	O	The type of the Item. It can be `image` or `video`. If not specified, it defaults to both.
folderID	string	O	The unique identifier of the Private or Public Folder. If not specified, it defaults to all Items. Use the special value `root` to get the content of the root Folder (i.e., the Items where `folderID` is `null`).
isPublic	boolean	O	Whether to return only Items with a specific public status. If not specified, it defaults to both.
publicApprovalStatus	string	O	Whether to return only Items that are currently in a specific approval process state. Possible values: `none`, `pending`, `approved`, `rejected`. If not specified, it defaults to all.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Items to return in the current request.
skipCount	number	O	The number of Items to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Image objects.

The response also contains the metadata object, corresponding to a PaginationMetadata object. In this case, the metadata object contains the totalCount property, corresponding to the estimated total number of Items that would be returned in the current request if the mtype, isPublic, and publicApprovalStatus parameters were not specified (i.e., it returns the same values from the User (itemCount, rootFolderItemCount) and Folder (imageCount) types).

Get Public Creations

This endpoint returns a list of Items that were made public by the corresponding Owner, and are currently placed in a Public Folder (Items with isPublic set to true that are not in a Public Folder will not be returned). Refer to Annex: Public Items Approval Workflow for more information.

HTTP Request

GET {BaseURL}/getPublicCreations

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User that owns the Item. If not specified, it defaults to all Users.
mtype	string	O	The type of the Item. It can be `image` or `video`. If not specified, it defaults to both.
folderID	string	O	The unique identifier of the Public Folder. If not specified, it defaults to all Items.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Items to return in the current request.
skipCount	number	O	The number of Items to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Image objects.

The response also contains the metadata object, corresponding to a PaginationMetadata object. In this case, the metadata object contains the totalCount property, corresponding to:

the estimated total number of Items in a specific Public Folder if the folderID parameter was specified (i.e., it returns the same values from the Folder (imageCount) types).
the exact total number of Items if the userID parameter was specified.
the exact total number of Items if neither the userID nor folderID parameters were specified.

In all cases, the totalCount property does not account for the mtype parameter. If the mtype parameter was specified, the totalCount property will still reflect the total number of Items that would be returned if the mtype parameter were not specified.

Get Batch Items

This endpoint returns a list of Items, owned by the User, that belong to the specified batch identified by the batchID.

HTTP Request

GET {BaseURL}/getBatchItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
batchID	string	M	The unique identifier of the batch of Items that should be returned.

HTTP Response

The response contains the payload object, corresponding to an array of ImageInfo objects.

Delete Items

This endpoint deletes one or more Items, removing them from their Folders (if any) and clearing their tags.

Deleting an Item will have no effect if any of the following conditions are met:

the Item is internally protected (isProtected: true set by an Admin).
the Item does not belong to the current User (not applicable if the API is used by an Admin).

In such cases, Users will need to contact the Admin to resolve the issue.

The API can also be used to delete all Items owned by the User. In this case, the userID parameter must be specified, corresponding to the unique identifier of the current User. In this case, the imageIDs parameter is ignored. Protected Items will not be deleted in any case.

Such feature is only available to Users whose PRO tier is higher than 2, and to Admins.

When used by Admins, the userID parameter can target any User and the imageIDs parameter can target any number of Items, regardless of their ownership.

HTTP Request

DELETE {BaseURL}/deleteItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	O	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
imageIDs	string	O	A comma-separated list of unique identifiers of Items. At least one of `imageIDs` or `userID` must be specified.
userID	string	O	The unique identifier of the User. At least one of `imageIDs` or `userID` must be specified.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully deleted.
message	string	If the Item was not successfully deleted, the reason for the failure.

Restore Items

This endpoint restores one or more Items, under the following rules:

the Item is already marked as deleted.
the Item will be restored under the root Folder of the current User, even if it was placed under a Folder when it was deleted.
the Item will be flagged as if it was just added to the root Folder in terms of sorting.
the Item will be untagged, even if it had tags when it was deleted.
the Item will be not flagged as public (isPublic: false), even if it was marked as public when it was deleted. The Public Approval Status will be retained.

The API can be used to restore all deleted Items owned by a User by specifying the userID parameter. In this case, the imageIDs parameter is ignored. The imageIDs parameter can target any number of Items, regardless of their ownership.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/restoreItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string	O	An array of unique identifiers of Items. At least one of `imageIDs` or `userID` must be specified.
userID	string	O	The unique identifier of the User. At least one of `imageIDs` or `userID` must be specified.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully restored.
message	string	If the Item was not successfully restored, the reason for the failure.

Report Items

This endpoint reports one or more Items, submitting them for further review by Admins.

Reporting an Item will have no effect if any of the following conditions are met:

the Item is internally protected (isProtected: true set by an Admin).
the Item is approved for public status (publicApprovalStatus: "approved").
the Item is already reported by the User and the report is not closed yet.

In such cases, Users may need to contact the Admin to resolve the issue.

HTTP Request

POST {BaseURL}/reportItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
itemIds	string[]	M	An array of unique identifiers of Items.
reportQueue	string	O	The report category. Possible values available through the Get Report Queues (non-Admin) endpoint. If not specified, it defaults to `Not Specified`.
additionalInformation	string	O	The additional information provided by the User regarding the report.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
reportId	string	The unique identifier of the report, or `null` if the Item report was not created.
success	boolean	Whether the Item was successfully reported.
message	string	If the Item was not successfully reported, the reason for the failure.

Get Reports

This endpoint lists the submitted reports, based on the provided filters.

This endpoint can currently only be used by Admins.

HTTP Request

GET {BaseURL}/getReports

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
reportIds	string	O	A comma-separated list of unique identifiers of reports. Used to filter results and return only the specified reports.
reportStatus	string	O	A comma-separated list of statuses of the reports. Possible values: `pending`, `accepted`, `declined`, `automaticallyDeclined`. If not specified, it defaults to all.
reportQueues	string	O	A comma-separated list of report categories. Possible values available through the Get Report Queues endpoint. If not specified, it defaults to all.
createdAfter	string	O	The date (as ISO 8601 string) after which the reports were submitted. Used to filter results and return only the reports submitted after the specified date (inclusive).
createdBefore	string	O	The date (as ISO 8601 string) before which the reports were submitted. Used to filter results and return only the reports submitted before the specified date (inclusive).
authorId	string	O	The unique identifier of the User who created the Item that was reported. Used to filter results and return only the reports corresponding to the specified User.

HTTP Response

The response contains the payload object, corresponding to an array of ItemReport objects.

Close Reports

This endpoint closes the submitted reports, assigning them a new status decided by the Admin.

If a report is accepted, the associated Items will be deleted, removing them from their Folders (if any) and clearing their tags.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/closeReports

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
reportIds	string[]	M	An array of unique identifiers of reports.
reportStatus	string	M	The status of the reports. Possible values: `accepted`, `declined`.
additionalInformation	string	O	The additional information provided by the Admin regarding the closure.
closeRelatedReports	boolean	O	Whether to extend the closure to other reports that share the same Item(s). When set to `true`, the `reportIds` input parameter is internally extended to include all reports that share the same Item(s). If not specified, it defaults to `false`.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the report.
success	boolean	Whether the report was successfully closed.
message	string	If the report was not successfully closed, the reason for the failure.

Get Report Queues

This endpoint lists the possible values for report queues.

When used by Admins, it will also show the possible system report queues (queues that are automatically created by the system based on internal parameters) to be used in the Get Reports endpoint. Otherwise, it will only show the report queues that can be used by the User through the Report Items endpoint.

HTTP Request

GET {BaseURL}/getReportQueues

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	O	The API Administration key for the current environment.

HTTP Response

The response contains the payload object, corresponding to an array of strings with possible values.

Download Reports For Epoch

This endpoint downloads the reports to be submitted to Epoch according to its compliance policy.

This endpoint can currently only be used by Admins.

HTTP Request

GET {BaseURL}/downloadReportsForEpoch

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
reportIds	string	M	A comma-separated list of unique identifiers of reports.

HTTP Response

This endpoint does not return any response. It downloads the reports as a CSV file.

Like Items

This endpoint adds a like to one or more Items.

Adding a like to an already disliked Item will remove the dislike from that Item, if any.

HTTP Request

POST {BaseURL}/likeItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string[]	M	An array of unique identifiers of Items.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully liked.
message	string	If the Item was not successfully liked, the reason for the failure.

Unlike Items

This endpoint removes a like from one or more Items.

HTTP Request

POST {BaseURL}/unlikeItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string[]	M	An array of unique identifiers of Items.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully unliked.
message	string	If the Item was not successfully unliked, the reason for the failure.

Dislike Items

This endpoint adds a dislike to one or more Items.

Adding a dislike to an already liked Item will remove the like from that Item, if any.

HTTP Request

POST {BaseURL}/dislikeItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string[]	M	An array of unique identifiers of Items.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully disliked.
message	string	If the Item was not successfully disliked, the reason for the failure.

Undislike Items

This endpoint removes a dislike from one or more Items.

HTTP Request

POST {BaseURL}/undislikeItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string[]	M	An array of unique identifiers of Items.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully undisliked.
message	string	If the Item was not successfully undisliked, the reason for the failure.

Set Item Properties

This endpoint edits properties (e.g., public approval status) for an existing Item owned by the User.

You can only toggle the public approval status of an Item between none and pending. Once an Item is set to approved or rejected, its public approval status cannot be changed. When an Item's public approval status is set to approved, its isPublic property can be toggled. Refer to Annex: Public Items Approval Workflow for more information.

At least one of the Item properties must be provided.

HTTP Request

POST {BaseURL}/setItemProperties

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the Item.
isPublic	boolean	O	Whether the Item is set to be public. It can only be set if the approval status is `approved`.
publicApprovalStatus	string	O	The new public approval status of the Item. Possible values: `none`, `pending`.

HTTP Response

The response contains the payload object, corresponding to a Image object.

Get Sample Items

This endpoint returns basic information about eligible sample Items, based on the specified criteria.

HTTP Request

GET {BaseURL}/getSampleItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
limit	number	O	The number of Items to return in the current request.

HTTP Response

The response contains the payload object, corresponding to an array of Image objects. Not all properties are returned for sample Items.

Get Latest Items

This endpoint returns basic information about the latest available Items, based on the specified criteria.

HTTP Request

GET {BaseURL}/getLatestItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Items to return in the current request.
skipCount	number	O	The number of Items to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Image objects. Not all properties are returned for sample Items.

The response also contains the metadata object, corresponding to a PaginationMetadata object. In this case, the metadata object does not contain the totalCount property.

Get Items

This endpoint returns basic information about all available Items, based on the specified criteria.

This endpoint can currently only be used by Admins.

HTTP Request

GET {BaseURL}/getItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
userID	string	O	The unique identifier of the User that owns the Item. If not specified, it defaults to all Users.
mtype	string	O	The type of the Item. It can be `image` or `video`. If not specified, it defaults to both.
folderID	string	O	The unique identifier of the Private or Public Folder. If not specified, it defaults to all Items. Use the special value `root` to get the content of the root Folder (i.e., the Items where `folderID` is `null`).
isPublic	boolean	O	Whether to return only Items with a specific public status. If not specified, it defaults to both.
publicApprovalStatus	string	O	Whether to return only Items that are currently in a specific approval process state. Possible values: `none`, `pending`, `approved`, `rejected`. If not specified, it defaults to all.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Items to return in the current request.
skipCount	number	O	The number of Items to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Image objects.

The response also contains the metadata object, corresponding to a PaginationMetadata object. In this case, the metadata object does not contain the totalCount property.

Set Public Approval Status

This endpoint updates the public approval status of one or more Items.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/setPublicApprovalStatus

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string	M	A comma-separated list of unique identifiers of Items.
publicApprovalStatus	string	M	The new public approval status of the Items. Possible values: `approved`, `rejected`.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully modified.
message	string	If the Item was not successfully modified, the reason for the failure.

Set Protected

This endpoint toggles the protected status of one or more Items. Protected Items cannot be deleted or reported.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/setProtected

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
imageIDs	string[]	M	An array of unique identifiers of Items.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully modified.
message	string	If the Item was successfully modified, the new protected status (as a textual string). If the Item was not successfully modified, the reason for the failure.

Migrate Library

This endpoint migrates an existing Library from a User's account to a new User. This includes Items and Folders in the Library.

The source User can be disabled, but the new User must not be disabled. Items and Folders that are deleted from the source User will not be moved to the new User.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/migrateLibrary

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
sourceUserID	string	M	The unique identifier of the source User.
destinationUserID	string	M	The unique identifier of the destination User.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the migration was successful.
message	string	An additional message that may be displayed on the front-end. It includes the number of Items and Folders that were moved.

Image Generation

Generate Image

This endpoint triggers the generation of a new image through the specified AI generation Model.

Check the Prompting101 page of the wiki for more information about the meaning of the body parameters.

The possible values for the body parameters can be found using the Get Models endpoint. A human-readable list of the possible values can be found in the Sexy.AI Model Object Info spreadsheet.

HTTP Request

POST {BaseURL}/generateImage

Body Parameters

Parameter	Type	M/O	Description
prompt	string	M	The prompt to be used to generate the Item.
negprompt	string	O	The negative prompt containing a list of concepts that should be avoided when generating the Item.
modelName	string	O	The unique identifier of the AI generation Model. Defaults to `f222`.
steps	number	O	The number of steps of the AI generation Model. Defaults to 20.
seed	number	O	The seed of the AI generation Model.
subseed	number	O	The subseed of the AI generation Model.
subseed_strength	number	O	The subseed strength of the AI generation Model.
height	number	O	The user-defined height of the resulting Item (if the AI generation Model supports that).
width	number	O	The user-defined width of the resulting Item (if the AI generation Model supports that).
sampler	string	O	The name of the AI generation sampler. Defaults to `DPM++ 2M Karras`.
cfgscale	number	O	The CFG scale of the AI generation sampler. Defaults to 7. The allowed range is [1, 12].
restoreFaces	boolean	O	Whether to restore faces using Facefix in the generated image. Defaults to `false`.
folderID	string	O	The unique identifier of the Folder. When specified, the Item will be automatically added to the Folder during generation.

HTTP Response

The response contains the payload object, corresponding to a GenerationStatus object.

Generate Video

This endpoint triggers the generation of a new video through the specified AI generation Model.

Check the Prompting101 page of the wiki for more information about the meaning of the body parameters.

The possible values for the body parameters can be found using the Get Models endpoint. A human-readable list of the possible values can be found in the Sexy.AI Model Object Info spreadsheet.

HTTP Request

POST {BaseURL}/generateVideo

Body Parameters

Parameter	Type	M/O	Description
prompt	string	M	The prompt to be used to generate the Item.
modelName	string	O	The unique identifier of the AI generation Model. Defaults to `model3`.
steps	number	O	The number of steps of the AI generation Model. Defaults to 20.
seed	number	O	The seed of the AI generation Model.
restoreFaces	boolean	O	Whether to restore faces using Facefix in the generated video. Defaults to `false`.
input	string	O	???
controlNetPreset	string	O	???
folderID	string	O	The unique identifier of the Folder. When specified, the Item will be automatically added to the Folder during generation.

HTTP Response

The response contains the payload object, corresponding to a GenerationStatus object.

Get Item Generation Status

This endpoint returns the current status of an Item being generated.

HTTP Request

GET {BaseURL}/getItemStatus

Query Parameters

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the Item.

HTTP Response

The response contains the payload object, corresponding to a GenerationStatus object.

Get Models

This endpoint returns the list of available AI generation Models and the corresponding parameters.

The front-end should show the Models in the order returned by this endpoint.

HTTP Request

GET {BaseURL}/getModels

Query Parameters

Parameter	Type	M/O	Description
modelIDs	string	O	A comma-separated list of unique identifiers of AI generation Models. Used to filter results and return only the specified Models.

HTTP Response

The response contains the payload object, corresponding to to an array of Model objects.

Get Queues Length

This endpoint returns the list of generation queues and their current length.

HTTP Request

GET {BaseURL}/getQueuesLength

Query Parameters

Parameter	Type	M/O	Description
modelIDs	string	O	A comma-separated list of unique identifiers of AI generation Models. Used to filter results and return only the specified Models.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
modelID	string	The unique identifier of the AI generation Model.
queueID	string	The unique identifier of the generation queue. Queues with `-p1-` in their name refer to priority queues for Pro users.
queueLength	number	The current length of the generation queue.

Get Sample Prompts

This endpoint returns the list of available sample prompts.

HTTP Request

GET {BaseURL}/getSamplePrompts

Query Parameters

Parameter	Type	M/O	Description
randomOne	boolean	O	Whether to return a single random sample prompt. Defaults to `false`.

HTTP Response

The response contains the payload object, corresponding to to an array of Prompt objects.

Private Folder Management

Get Private Folders

This endpoint provides the list of Private Folders owned by the User.

Private Folders' unique identifiers are simple UUIDs.

HTTP Request

GET {BaseURL}/getSelfFolders

Query Parameters

Parameter	Type	M/O	Description
folderIDs	string	O	A comma-separated list of unique identifiers of Folders. Used to filter results and return only the specified Folders.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Folders to return in the current request.
skipCount	number	O	The number of Folders to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Folder objects.

Create Private Folder

This endpoint creates a new Private Folder owned by the User.

The allowed folder name length is [1, 64].
The allowed folder description length is [0, 256].
These characters are not allowed in the folder name or description: < > : " % / \ | ? * ^ $.

HTTP Request

POST {BaseURL}/createSelfFolder

Body Parameters

Parameter	Type	M/O	Description
name	string	M	The name of the Folder.
description	string	O	The description of the Folder.

HTTP Response

The response contains the payload object, corresponding to a Folder object.

Set Private Folder Properties

This endpoint edits properties (e.g., name and/or description) for an existing Private Folder owned by the User.

The allowed folder name length is [1, 64].
The allowed folder description length is [0, 256].
These characters are not allowed in the folder name or description: < > : " % / \ | ? * ^ $.

At least one of the Folder properties must be provided.

HTTP Request

POST {BaseURL}/setSelfFolderProperties

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
folderName	string	O	The new name of the Folder.
folderDescription	string	O	The new description of the Folder. Pass an empty string to delete the current description.

HTTP Response

The response contains the payload object, corresponding to a Folder object.

Delete Private Folder

This endpoint deletes an existing Private Folder owned by the User. If the Folder is not empty, all Items will be removed from the Folder and moved to the root Folder.

HTTP Request

DELETE {BaseURL}/deleteSelfFolder

Query Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the Folder was successfully deleted.

Add Items to Private Folder

This endpoint adds a set of Items (images/videos) to a specified Private Folder owned by the User.

When it comes to bulk adding Items:

There's a upper limit of 1,000 Items that can be added in a single API call.
The outcome is true when at least one Item is correctly added to the Folder after cleaning up invalid Items. In the future, the outcome will be an array of outcomes specifying whether the individual Item was correctly added to the Folder.

HTTP Request

POST {BaseURL}/addImagesToSelfFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to add to the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully added to the Folder.

Remove Items from Private Folder

This endpoint removes a set of Items (images/videos) from a specified Private Folder owned by the User.

When it comes to bulk removing Items:

There's a upper limit of 1,000 Items that can be removed in a single API call.
The outcome is true when at least one Item is correctly removed from the Folder after cleaning up invalid Items. In the future, the outcome will be an array of outcomes specifying whether the individual Item was correctly removed from the Folder.

HTTP Request

POST {BaseURL}/removeImagesFromSelfFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to remove from the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully removed from the Folder.

Add Thumbnails to Private Folder

This endpoint adds a set of Items (images/videos) as Thumbnails to a specified Private Folder owned by the User.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/addThumbnailImagesForSelfFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to add as Thumbnail to the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully added as Thumbnail to the Folder.
modified	string[]	The list of Items that were actually added as Thumbnail to the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnail to the Folder after the current request.

Remove Thumbnails from Private Folder

This endpoint removes a set of Items (images/videos) as Thumbnails from a specified Private Folder owned by the User.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/removeThumbnailImagesForSelfFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to remove as Thumbnail from the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully removed as Thumbnail from the Folder.
modified	string[]	The list of Items that were actually removed as Thumbnail from the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnail to the Folder after the current request.

Set Thumbnails for Private Folder

This endpoint sets a list of Items (images/videos) as Thumbnails for a specified Private Folder owned by the User, replacing any existing Thumbnails.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/setThumbnailImagesForSelfFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to set as Thumbnails for the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the list of Items was successfully set as Thumbnails for the Folder.
modified	string[]	The list of Items that were actually set as Thumbnails for the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnails for the Folder after the current request.

Public Folder Management

Get Public Folders

This endpoint provides the list of Public Folders.

Public Folders' unique identifiers are UUIDs prepended with p-.

Public Folders can be retrieved by any User. They can only contain Items that are set as Public (isPublic is set to true). Refer to Annex: Public Items Approval Workflow for more information.

HTTP Request

GET {BaseURL}/getPublicFolders

Query Parameters

Parameter	Type	M/O	Description
userID	string	O	The identifier of the User that owns the Public Folders. If not provided, all Public Folders are returned. You must explicitly specify the `userID` of the current User to retrieve only the Folders owned by the User.
folderIDs	string	O	A comma-separated list of unique identifiers of Folders. Used to filter results and return only the specified Folders.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of Folders to return in the current request.
skipCount	number	O	The number of Folders to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Folder objects.

Create Public Folder

This endpoint creates a new Public Folder owned by the User.

The allowed folder name length is [1, 64].
The allowed folder description length is [0, 256].
These characters are not allowed in the folder name or description: < > : " % / \ | ? * ^ $.

HTTP Request

POST {BaseURL}/createPublicFolder

Body Parameters

Parameter	Type	M/O	Description
name	string	M	The name of the Folder.
description	string	O	The description of the Folder.

HTTP Response

The response contains the payload object, corresponding to a Folder object.

Set Public Folder Properties

This endpoint edits properties (e.g., name and/or description) for an existing Public Folder owned by the User.

The allowed folder name length is [1, 64].
The allowed folder description length is [0, 256].
These characters are not allowed in the folder name or description: < > : " % / \ | ? * ^ $.

At least one of the Folder properties must be provided.

HTTP Request

POST {BaseURL}/setPublicFolderProperties

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
folderName	string	O	The new name of the Folder.
folderDescription	string	O	The new description of the Folder. Pass an empty string to delete the current description.

HTTP Response

The response contains the payload object, corresponding to a Folder object.

Delete Public Folder

This endpoint deletes an existing Public Folder owned by the User. If the Folder is not empty, all Items will be removed from the Folder and moved to the root Folder.

HTTP Request

DELETE {BaseURL}/deletePublicFolder

Query Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the Folder was successfully deleted.

Add Items to Public Folder

This endpoint adds a set of Items (images/videos) to a specified Public Folder owned by the User.

When it comes to bulk adding Items:

There's a upper limit of 1,000 Items that can be added in a single API call.
The outcome is true when at least one Item is correctly added to the Folder after cleaning up invalid Items. In the future, the outcome will be an array of outcomes specifying whether the individual Item was correctly added to the Folder.

HTTP Request

POST {BaseURL}/addImagesToPublicFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to add to the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully added to the Folder.

Remove Items from Public Folder

This endpoint removes a set of Items (images/videos) from a specified Public Folder owned by the User.

When it comes to bulk removing Items:

There's a upper limit of 1,000 Items that can be removed in a single API call.
The outcome is true when at least one Item is correctly removed from the Folder after cleaning up invalid Items. In the future, the outcome will be an array of outcomes specifying whether the individual Item was correctly removed from the Folder.

HTTP Request

POST {BaseURL}/removeImagesFromPublicFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to remove from the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully removed from the Folder.

Add Thumbnails to Public Folder

This endpoint adds a set of Items (images/videos) as Thumbnails to a specified Public Folder owned by the User.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/addThumbnailImagesForPublicFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to add as Thumbnail to the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully added as Thumbnail to the Folder.
modified	string[]	The list of Items that were actually added as Thumbnail to the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnail to the Folder after the current request.

Remove Thumbnails from Public Folder

This endpoint removes a set of Items (images/videos) as Thumbnails from a specified Public Folder owned by the User.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/removeThumbnailImagesForPublicFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to remove as Thumbnail from the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one Item was successfully removed as Thumbnail from the Folder.
modified	string[]	The list of Items that were actually removed as Thumbnail from the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnail to the Folder after the current request.

Set Thumbnails for Public Folder

This endpoint sets a list of Items (images/videos) as Thumbnails for a specified Public Folder owned by the User, replacing any existing Thumbnails.

There can only be a maximum of 4 Thumbnails set for a Folder.

HTTP Request

POST {BaseURL}/setThumbnailImagesForPublicFolder

Body Parameters

Parameter	Type	M/O	Description
folderID	string	M	The unique identifier of the Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to set as Thumbnails for the Folder.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the list of Items was successfully set as Thumbnails for the Folder.
modified	string[]	The list of Items that were actually set as Thumbnails for the Folder through the current request.
actual	string[]	The list of Items that are applied as Thumbnails for the Folder after the current request.

Common Folder Management

Move Items Between Folders

This endpoint moves a set of Items (images/videos) from one Folder to a different Folder owned by the User. It can be used to move Items from one Folder to another regardless of the Private or Public nature of the Folders. When attempting to move Items to a Public Folder, the Items will only be moved if they are eligible.

When it comes to bulk moving Items, there's a upper limit of 1,000 Items that can be moved in a single API call.

HTTP Request

POST {BaseURL}/moveItemsBetweenFolders

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Body Parameters

Parameter	Type	M/O	Description
sourceFolderID	string	M	The unique identifier of the Source Folder. Use `null` for the root Folder.
destinationFolderID	string	M	The unique identifier of the Destination Folder. Use `null` for the root Folder.
imageIDs	string[]	M	An array of unique identifiers of Items to move between Folders.

HTTP Response

The response contains the payload object, corresponding to an array of objects with following parameters:

Parameter	Type	Description
id	string	The unique identifier of the Item.
success	boolean	Whether the Item was successfully moved.
message	string	If the Item was not successfully moved, the reason for the failure.

Tags Management

Get Enrolled Tags

This endpoint provides the list of tags (up to 100) that were already applied to an Item at least once, sorted by usage count (descending).

HTTP Request

GET {BaseURL}/getTagsList

Query Parameters

Parameter	Type	M/O	Description
tags	string	O	A comma-separated list of tags. Used to filter results and return only the specified tags.
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their creation timestamp is less than this value.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. Together with `paginationIndex`, this parameter can be used to paginate through results in reverse order (i.e., from the oldest to the newest).
limit	number	O	The number of tags to return in the current request.
skipCount	number	O	The number of tags to skip in the current request. Use this to paginate through results.

HTTP Response

The response contains the payload object, corresponding to an array of Tag objects.

Add Tags to an Item

This endpoint adds a set of tags (identified by their name) to a specified Item owned by the User.

Tags can currently be applied to images/videos, and folders.
The allowed tag name length is [1, 32].
Tag names are lower case (passing a tag name with upper cases is allowed, it will be automatically converted to lower cases), and must adhere to the following regular expression: ^[a-z0-9$-_\.\+!\*']{1,32}$
There can only be a maximum of 10 tags applied to an Item.

HTTP Request

POST {BaseURL}/addTagsToItem

Body Parameters

Parameter	Type	M/O	Description
tags	string[]	M	An array of tags to add to the Item.
imageID	string	O	The unique identifier of the Item. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.
folderID	string	O	The unique identifier of the Folder. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one tag was successfully added to the Item.
modified	string[]	The list of tags that were actually added to the Item through the current request.
actual	string[]	The list of tags that are applied to the Item after the current request.

Remove Tags from an Item

This endpoint removes a set of tags (identified by their name) from a specified Item owned by the User.

Tags can currently be applied to images/videos, and folders.
The allowed tag name length is [1, 32].
Tag names are lower case (passing a tag name with upper cases is allowed, it will be automatically converted to lower cases), and must adhere to the following regular expression: ^[a-z0-9$-_\.\+!\*']{1,32}$
There can only be a maximum of 10 tags applied to an Item.

HTTP Request

POST {BaseURL}/removeTagsFromItem

Body Parameters

Parameter	Type	M/O	Description
tags	string[]	M	An array of tags to remove from the Item.
imageID	string	O	The unique identifier of the Item. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.
folderID	string	O	The unique identifier of the Folder. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether at least one tag was successfully removed from the Item.
modified	string[]	The list of tags that were actually removed from the Item through the current request.
actual	string[]	The list of tags that are applied to the Item after the current request.

Set Tags for an Item

This endpoint sets a list of tags (identified by their name) for a specified Item owned by the User, replacing any existing tags.

Tags can currently be applied to images/videos, and folders.
The allowed tag name length is [1, 32].
Tag names are lower case (passing a tag name with upper cases is allowed, it will be automatically converted to lower cases), and must adhere to the following regular expression: ^[a-z0-9$-_\.\+!\*']{1,32}$
There can only be a maximum of 10 tags applied to an Item.

HTTP Request

POST {BaseURL}/setTagsForItem

Body Parameters

Parameter	Type	M/O	Description
tags	string[]	M	An array of tags to set for the Item.
imageID	string	O	The unique identifier of the Item. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.
folderID	string	O	The unique identifier of the Folder. At least one between `imageID` and `folderID` must be passed in the request. If both are passed, `folderID` gets priority.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the list of tags was successfully set for the Item.
actual	string[]	The list of tags that are applied to the Item after the current request.

Technical

Logs Ingestion

This endpoint allows front-end clients to ingest logs into the centralized logging system.

HTTP Request

POST {BaseURL}/ingestLogs

Headers

Parameter	Type	M/O	Description
X-Request-ID	string	M	The unique identifier of the request. Usually a UUID. If ingesting logs that are related to an API call, it is recommended to set this header as the `X-Request-ID` header from the API response to ensure that front-end and back-end logs can be correlated. If not set, a UUID will be generated automatically.
X-Session-ID	string	O	The unique identifier of the current session. It must be a valid UUID. Mandatory if `X-Administration-Key` is not set.
X-Administration-Key	string	O	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
serviceName	string	O	The name of the Service. If not provided, it will default to `FrontEnd/Client/{DomainDisplayName}/{EnvironmentIdentifier}`. If provided, it must follow a similar format.
logs	LogEntry[]	M	The logs to ingest.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the logs were successfully ingested.

Get Affiliate Ad

This endpoint allows front-end clients to get an Affiliate Ad to display on the website.

HTTP Request

GET {BaseURL}/getAffiliateAd

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
adText	string	The affiliate ad text.
adLink	string	The affiliate ad link.

Upload File

This endpoints allows authorized clients to upload files on the internal File Server, built on SeaweedFS.

This endpoint can currently only be used by Admins.

The request must be sent as a multipart/form-data request, with the file as the file to upload and filename as the name of the file. Additional parameters must be passed as form-data fields.

HTTP Request

POST {BaseURL}/uploadFile

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
file	file	M	The File to upload. It is suggested to use `form-data` with the `filename` parameter to specify the name of the File.
id	string	O	A unique identifier of the File, defined by the client. If not provided, a unique identifier will be generated automatically.
customMetadata	string	O	A JSON string containing the custom metadata of the File. If not provided, no custom metadata will be set.

HTTP Response

The response contains the payload object, corresponding to a FileMetadata object.

Get File

This endpoints allows front-end clients to get files on the internal File Server, built on SeaweedFS.

Files will be served with the Content-Disposition header set to inline, and the Content-Type header set to the MIME type of the file.

SeaweedFS supports resizing images on the fly for the following extensions: png, jpg, jpeg, gif. When resizing, the checksum check will not be performed.

HTTP Request

GET {BaseURL}/getFile

Query Parameters

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the File.
skipChecksum	boolean	O	Whether to skip the checksum check. If not provided, the checksum check will be performed and an error will be returned if the checksum check fails.
width	number	O	The desired width of the image.
height	number	O	The desired height of the image.
mode	string	O	The desired resize mode. Possible values: `fit`, `fill`.
fs	boolean	O	Whether to also fetch files from the old File Server, if not found on the new File Server. If not provided, the old File Server will not be checked.

HTTP Response

The File will be served with the Content-Disposition header set to inline, and the Content-Type header set to the MIME type of the file.

Get File Metadata

This endpoints allows authorized clients to get metadata of files on the internal File Server, built on SeaweedFS.

This endpoint can currently only be used by Admins.

HTTP Request

GET {BaseURL}/getFileMetadata

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the File.

HTTP Response

The response contains the payload object, corresponding to a FileMetadata object.

Remove File

This endpoints allows authorized clients to remove files on the internal File Server, built on SeaweedFS.

This endpoint can currently only be used by Admins.

HTTP Request

DELETE {BaseURL}/removeFile

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Query Parameters

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the File.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
success	boolean	Whether the File was successfully removed.

PostgreSQL Query Wrapper

This endpoint allows sending SQL queries to the PostgreSQL database. The internal implememtation uses the pg Node.js library, refer to the pg documentation for more information.

This endpoint can currently only be used by Admins.

HTTP Request

POST {BaseURL}/pgQuery

Headers

Parameter	Type	M/O	Description
X-Administration-Key	string	M	The API Administration key for the current environment.

Body Parameters

Parameter	Type	M/O	Description
queryText	string	M	The raw SQL query text. It maps to the `text` parameter in the pg documentation.
queryParams	any[]	O	An array of query parameters. It maps to the `values` parameter in the pg documentation.

HTTP Response

The response contains the payload object, which contains the result of the query as described in the pg documentation.

API2: User Management

Get User Session

This endpoint triggers the creation of a new User session on API2 (the backend that handles the new workflows generation system) and returns the session and User information. Using this endpoint is generally not needed and should be avoided, as API2 sessions are created automatically when a User triggers an API2 endpoint.

API2 endpoints can only be called by authenticated Users whose PRO tier is higher than 0.

HTTP Request

GET {BaseURL}/2/getUserSession

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

HTTP Response

The response contains the payload object, with following parameters:

Parameter	Type	Description
userSession	object	The API2 User session.
userSession._id	string	The unique identifier of the User session.
userSession.domain	string	The domain of the User.
userSession.isAtLeast18Confirmed	boolean	Whether the User has confirmed being 18+ years old.
userSession.updatedDate	string	The last update date of the User, as ISO 8601 string.
userSession.userID	string	The unique identifier of the User.
user	object	The API2 User.
user._id	string	The unique identifier of the User.
user.email	string	The email of the User.
user.username	string	The username of the User.
user.domain	string	The domain of the User.
user.createdDate	string	The creation date of the User, as ISO 8601 string.
user.isDisabled	boolean	Whether the User is disabled.
user.roles	string[]	The roles of the User.
user.flaggedImagesCount	number	The number of flagged images of the User.

API2: Workflows

Get Aggregated Workflow Templates

This endpoint returns a list of all available Workflow Templates.

API2 endpoints can only be called by authenticated Users whose PRO tier is higher than 0. A valid session ID must be provided in the X-Session-ID header.

HTTP Request

GET {BaseURL}/2/getAggregatedWorkflowTemplates

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
workflowTemplateNames	string	O	A comma-separated list of Workflow Template names. Used to filter results and return only the specified Workflow Templates.

HTTP Response

The response contains the payload object, corresponding to to an array of WorkflowTemplate objects.

Get File Group Items

For Workflow Templates that support multiple file groups, this endpoint returns all the files that are associated with a specific file group.

HTTP Request

GET {BaseURL}/2/getFileGroupItems

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
fileGroup	string	M	The name of the file group, as defined in the Workflow Template.

HTTP Response

The response contains the payload object, with the following parameters:

Parameter	Type	Description
fileNames	string[]	An array of file names associated with the file group.

Get Workflow Status

This endpoint returns the status of a specific Workflow, while it is running. This is functionally equivalent to the Get Item Generation Status endpoint, and both can be used interchangeably for workflows started by API2 - with different input parameters and outputs.

This endpoints supports requests with multiple Workflow IDs.

HTTP Request

GET {BaseURL}/2/getWorkflowStatus

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Query Parameters

Parameter	Type	M/O	Description
workflowId	string	O	The unique identifier of the Workflow. At least one of these parameters is required.
workflowIds	string	O	A comma-separated list of unique identifiers of Workflow. At least one of these parameters is required.

HTTP Response

The response contains the payload object, corresponding to a WorkflowStateObject object or an array of WorkflowStateObject objects.

Enqueue Workflow

This endpoint enqueues a new Workflow, based on the specified Workflow Template.

This endpoint can only be called by authenticated Users whose PRO tier is higher than 0. A valid session ID must be provided in the X-Session-ID header.

By default, the API2 Workflow Engine will require passing the parameters through the parameters array. To ensure consistency and backward compatibility, some parameters can also be passed through explicit parameters in the request body.

The response of this endpoint will provide both the Workflow ID and the list of Item IDs associated with the Workflow.

HTTP Request

POST {BaseURL}/2/enqueueWorkflow

Headers

Parameter	Type	M/O	Description
X-Session-ID	string	M	The unique identifier of the current session. It must be a valid UUID.

Request Body

Parameter	Type	M/O	Description
prompt	string	O	The positive prompt for the Workflow generation. Corresponds to passing the `Positive Prompt` parameter.
negprompt	string	O	The negative prompt for the Workflow generation. Corresponds to passing the `Negative Prompt` parameter.
seed	number	O	The seed for the Workflow generation. Corresponds to passing the `Seed` parameter.
subseed	number	O	The subseed of the Workflow generation. Corresponds to passing the `Subseed` parameter.
subseed_strength	number	O	The subseed strength of the Workflow generation. Corresponds to passing the `Subseed Strength` parameter.
steps	number	O	The number of steps for the Workflow generation. Corresponds to passing the `Steps` parameter.
cfgscale	number	O	The CFG scale for the Workflow generation. Corresponds to passing the `CFG Scale` parameter.
modelName	string	O	The model name for the Workflow generation. Corresponds to passing the `Model` parameter.
lora	string[]	O	The lora name(s) for the Workflow generation. The order of the names must match the order of the lora strengths. Corresponds to passing the `Lora X` parameter(s).
lora_strength	number[]	O	The lora strength(s) for the Workflow generation. The order of the strengths must match the order of the lora names. Corresponds to passing the `Lora X Strength` parameter(s).
height	number	O	The height for the Workflow generation. Corresponds to passing the `Height` parameter.
width	number	O	The width for the Workflow generation. Corresponds to passing the `Width` parameter.
batchSize	number	O	The number of Items to generate per batch. Corresponds to passing the `Batch Size` parameter.
workflowTemplateName	string	M	The name of the Workflow Template to use for the Workflow generation.
parameters	WorkflowRunParameter[]	O	The parameters for the Workflow generation.
folderID	string	O	The unique identifier of the Folder. When specified, the Item will be automatically added to the Folder during generation.

HTTP Response

The response contains the payload object, with the following parameters:

Parameter	Type	Description
itemIds	string[]	The unique identifiers of the Items generated by the Workflow. These identifiers can be used in subsequent Get Item Generation Status requests.
workflowId	string	The unique identifier of the Workflow. This identifier can be used in subsequent Get Workflow Status requests.

Annex: Pagination

For all endpoints that support pagination, there are two possible ways to paginate:

Use the limit and paginationIndex parameters (suggested).
Use the limit and skipCount parameters (not recommended due to very bad performance).

It is strongly recommended not to use the paginationIndex and skipCount parameters together due to the unpredictable results that can occur, and the performance implications.

The response of a paginated endpoint contains a metadata object (of type PaginationMetadata) with the following parameters:

paginationIndex: The pagination index that was used in the current request.
nextPaginationIndex: The pagination index to be used to fetch the next set of items.
reversePagination: Whether the pagination should be handled in reverse order.
skipCount: The number of items skipped in the current request.
limit: The maximum number of items returned in the current request.
count: The number of items returned in the current request.

In some cases, the metadata object may also contain the totalCount parameter. This is to be treated as a convenience parameter, representing an estimate of the total number of items that the request may return through pagination. More information about the presence and meaning of the totalCount parameter will be provided in the documentation for the corresponding endpoint.

Using limit and paginationIndex

This approach is recommended as it is drastically more efficient than using the skipCount parameter, but it doesn't allow the client to jump to a specific "page" of results without having to fetch all of the previous pages. The UX of this approach is very similar to an "infinite scroll" approach.

The paginationIndex parameter is a stringified integer that represents a timestamp (UNIX epoch, in milliseconds). When not specified, paginationIndex is implied to be the current time but will be returned as 0 in the response metadata of a paginated endpoint.

When using the paginationIndex parameter, the results returned will be sorted by a reference timestamp, in descending order (newest to oldest). Items will be returned if the reference timestamp of the item is less than the paginationIndex parameter that was used in the current request.

The reference timestamp depends on the endpoint, but it's typically the timestamp of creation (or, in some cases, the timestamp of the last update) of the item.

The nextPaginationIndex parameter is the pagination index to be used to fetch the next set of items. This parameter usually corresponds to the reference timestamp of the last item returned in the current request. It is returned in the response metadata of a paginated endpoint so that the client can use it to fetch the next set of items without having to calculate the pagination index. If no more items are available, nextPaginationIndex will be returned as null in the response metadata.

The reversePagination parameter is a boolean that indicates whether the results should be returned in reverse order. When not specified, reversePagination is set to false. When set to true, items will be returned in ascending order (oldest to newest). Use this parameter to fetch items on a "page" before the current page. The paginationIndex parameter should be manually adjusted accordingly, by identifying the reference timestamp of the newest item on the current page (e.g., for images and videos, this parameter corresponds to the completedDate parameter).

The limit parameter is the maximum number of items to return in the current request. This number must be less than or equal to 1000. When not specified, limit is set to 100.

Using limit and skipCount

This approach allows the client to jump to a specific "page" of results without having to fetch all of the previous pages by specifying a certain skipCount parameter (and knowing the total number of items that the request may return through pagination, which is usually returned in the totalCount parameter in the metadata object). On the other hand, using the paginationIndex parameter is strongly recommended due to the very bad performance that will occur when fetching a lot of items (refer to this page for more information: https://www.mongodb.com/docs/manual/reference/method/cursor.skip/#using-skip--).

The skipCount parameter is the number of items to skip before returning the first item.

The limit parameter is the number of items to return in the current request. This number must be less than or equal to 1000. When not specified, limit is set to 100.

Annex: Common Types

This chapter lists some common types that are mentioned throughout the API documentation.

SelfUser

Parameter	Type	M/O	Description
sessionID	string	M	The identifier of the current session of the User. It must be a valid UUID.
userID	string	M	The unique identifier of the User.
email	string	M	The email of the User.
username	string	M	The chosen username of the User.
isAuthenticated	boolean	M	Whether the User is currently authenticated.
isAtLeast18Confirmed	boolean	M	Whether the User has confirmed being 18+ years old.
profilePicture	string	O	The Profile Picture of the User, returned as base64 Data URI. Only returned when `profilePicture` is requested.
tier	number	M	The User PRO tier.
tierExpiration	string	O	The timestamp (as ISO 8601 string) of when the User's tier will expire.
merchantProcessor	string	M	The merchant processor that generated the PRO status.
subscriptions	Subscription[]	M	The list of PRO subscriptions of the User.
itemCount	number	M	The number of Items owned by the User.
rootFolderItemCount	number	M	The number of Items owned by the User and contained in the root Folder.

Subscription

Parameter	Type	M/O	Description
merchantProcessor	string	M	The merchant processor that generated the PRO status.
tier	number	M	The User PRO tier.
tierExpiration	string	O	The timestamp (as ISO 8601 string) of when the User's tier will expire.
nextBillingDate	string	O	The timestamp (as ISO 8601 string) of when the next billing date will be.
productID	string	M	The identifier of the product related to the Billing Plan that the User is subscribed to.
payerID	string	O	The unique identifier of the payer of the subscription, usually mapping to the identifier of the User within the payment provider.
transactionID	string	O	The unique identifier of the transaction of the subscription, usually mapping to the identifier of the subscription contract or payment transaction within the payment provider.
additionalInformation	string	O	The additional information associated with the subscription.
price	number	O	The Billing Plan pricing information of the subscription. Only returned when `extendedPriceInfo` is requested.
price.type	string	M	The type of the Billing Plan. Refer to the BillingPlanPrice type for more information.
price.period	string	M	The period of the Billing Plan. Refer to the BillingPlanPrice type for more information.
price.currency	string	M	The currency of the Billing Plan. Refer to the BillingPlanPrice type for more information.
price.currencyType	string	M	The type of the currency. Refer to the BillingPlanPrice type for more information.
price.value	number	M	The value of the Billing Plan.

LoginProvider

Parameter	Type	M/O	Description
providerType	string	M	The type of Login Provider. Possible values: `internal`, `oauth`.
providerId	string	M	The identifier of the Login Provider. Possible values: `OTP`, `Password` in case of `internal`; `Discord`, `GitHub`, `Google`, `Patreon` in case of `oauth`.
userId	string	O	The unique identifier of the User within the `oauth` Login Provider. If the Login Provider is `internal`, this field is not returned.

ArchivedEmail

Parameter	Type	M/O	Description
email	string	M	The email of the User.
archivedDate	string	M	The timestamp (as ISO 8601 string) of when the email was archived.

Folder

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the Folder.
name	string	M	The name of the Folder.
description	string	O	The description of the Folder.
userID	string	M	The unique identifier of the User that owns the Folder.
isPublic	boolean	M	Whether the Folder is public or not.
imageCount	number	M	The number of images contained in the Folder.
sampleImages	ImageThumbnail[]	M	An array representing a subset of images (maximum 4) among those contained by the Folder. Useful to generate Folder content previews. Automatically generated.
thumbnails	ImageThumbnail[]	M	An array representing a subset of images (maximum 4) among those contained by the Folder. Useful to generate Folder content previews. Generated by the user through specific APIs.
createdDate	Date	M	The date and time of when the Folder was first created.
updatedDate	Date	M	The date and time of when the Folder was last updated (renamed, adding/removing images).
tags	string[]	M	The list of tags that are applied to the Folder.

FolderItem

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the Folder Item.
mtype	string	M	The type of the Folder Item. It can be `image` or `video`.
userID	string	M	The unique identifier of the User that owns the Folder Item.
folderID	string	M	The unique identifier of the Folder.
imageID	string	M	The unique identifier of the Item.
url	string	M	The URL of the Item.
viewCount	number	M	The number of overall views for the Item.
likeCount	number	M	The number of overall likes that the Item received.
dislikeCount	number	M	The number of overall dislikes that the Item received.
createdDate	Date	M	The date and time of when the Folder Item was first created.
tags	string[]	M	The list of tags that are applied to the Item.

Tag

Parameter	Type	M/O	Description
name	string	M	The name of the tag. Tag names are lower case, and must adhere to the following regular expression: `^[a-z0-9$-_\.\+!\*']{1,32}$`
usageCount	number	O	The number of Items the tag is being used on.

GenerationStatus

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the resulting Item.
folderID	string	O	The unique identifier of the output Folder, if any.
status	string	M	The current generation status of the Item.
ignoredWords	string	M	The list of words that were ignored in the prompt, if any.
mtype	string	M	The type of the Item. It can be `image` or `video`.
url	string	O	The URL of the Item.
queuePosition	number	O	The current position of the Item in the generation queue.
frames	VideoFrame[]	O	An array representing the frames of the video. Only returned if `mtype` is `video`.

VideoFrame

Parameter	Type	M/O	Description
frameCount	number	M	The total number of frames in the video.
frameNumber	number	M	The number of the frame. The first frame is 0. The last frame is `frameCount - 1`.
frameUrl	string	M	The URL of the image representing the frame.

Image

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the Item.
userID	string	O	The unique identifier of the User that owns the Item.
batchID	string	O	The unique identifier of the batch of Items the Item belongs to.
url	string	M	The URL of the Item.
viewCount	number	O	The number of overall views for the Item.
likeCount	number	O	The number of overall likes that the Item received.
dislikeCount	number	O	The number of overall dislikes that the Item received.
completedDate	number	O	The timestamp (as Unix epoch) of when the Item generation finished.
completedTimestamp	string	O	The timestamp (as ISO 8601 string) of when the Item generation finished.
mtype	string	M	The type of the Item. It can be `image` or `video`.
mediaType	string	M	The media type of the Model that generated the Item. Possible values: `StaticImage`, `AnimatedImage`, `Video`, `Text`, `Music`, `Other`, `Unknown`.
tags	string[]	O	The list of tags that are applied to the Item.
isLiked	boolean	O	Whether the current User has liked the Item.
isDisliked	boolean	O	Whether the current User has disliked the Item.
isPublic	boolean	M	Whether the Item has been marked as public by the User (and approved by an Admin).
isPubliclyVisible	boolean	O	Whether the Item is publicly visible. It is `true` if the Item is public (`isPublic` is `true`) and the Item is in a Public Folder (`folderID` is not `null` and corresponds to a Public Folder).
publicApprovalStatus	string	O	Current status of the approval process for the Item. Only returned if the User requesting the Item is the owner of the Item, or an Admin. Possible values: `none`, `pending`, `approved`, `rejected`.
folderID	string	O	The unique identifiers of the Folder that contains the Item (if any).
folderAddedDate	number	O	The timestamp (as Unix epoch) of when the Item was added to the Folder (if any).
folderAddedTimestamp	string	O	The timestamp (as ISO 8601 string) of when the Item was added to the Folder (if any).

ImageInfo

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the Item.
userID	string	O	The unique identifier of the User that owns the Item.
batchID	string	O	The unique identifier of the batch of Items the Item belongs to.
username	string	O	The username of the User that owns the Item.
profilePicture	string	O	The Profile Picture of the User that owns the Item.
url	string	M	The URL of the Item.
viewCount	number	M	The number of overall views for the Item.
likeCount	number	M	The number of overall likes that the Item received.
dislikeCount	number	M	The number of overall dislikes that the Item received.
completedDate	number	O	The timestamp (as Unix epoch) of when the Item generation finished.
completedTimestamp	string	O	The timestamp (as ISO 8601 string) of when the Item generation finished.
prompt	string	M	The prompt to be used to generate the Item.
negprompt	string	O	The negative prompt containing a list of concepts that should be avoided when generating the Item.
generatorVersion	string	M	The version of the AI generation system used to generate the Item. Possible values: `1` for the legacy Generator, `2` for the new Workflows system.
workflowTemplateName	string	O	The name of the AI generation Workflow template used to generate the Item (only returned if the Item was generated by the workflows system).
workflowRunParameters	WorkflowRunParameter[]	O	The parameters of the AI generation Workflow used to generate the Item (only returned if the Item was generated by the workflows system).
modelName	string	M	The human-readable name of the AI generation Model.
modelID	string	M	The unique identifier of the AI generation Model.
steps	number	M	The number of steps of the Item.
seed	number	M	The seed of the Item.
subseed	number	M	The subseed of the Item.
subseed_strength	number	M	The subseed strength of the Item.
lora	string[]	M	The lora name(s) used to generate the Item. The order of the names matches the order of the lora strengths.
lora_strength	number[]	M	The lora strength(s) used to generate the Item. The order of the strengths matches the order of the lora names.
sampler	string	M	The name of the AI generation sampler.
cfgscale	number	M	The CFG scale of the AI generation sampler.
restoreFaces	boolean	M	Whether faces were restored using Facefix in the generated image.
height	number	M	The height of the Item.
width	number	M	The width of the Item.
mtype	string	M	The type of the Item. It can be `image` or `video`.
tags	string[]	O	The list of tags that are applied to the Item.
isLiked	boolean	O	Whether the current User has liked the Item.
isDisliked	boolean	O	Whether the current User has disliked the Item.
isPublic	boolean	M	Whether the Item has been marked as public by the User (and approved by an Admin).
isPubliclyVisible	boolean	O	Whether the Item is publicly visible. It is `true` if the Item is public (`isPublic` is `true`) and the Item is in a Public Folder (`folderID` is not `null` and corresponds to a Public Folder).
publicApprovalStatus	string	O	Current status of the approval process for the Item. Only returned if the User requesting the Item is the owner of the Item, or an Admin. Possible values: `none`, `pending`, `approved`, `rejected`.
folderID	string	O	The unique identifiers of the Folder that contains the Item (if any).

ImageThumbnail

Parameter	Type	M/O	Description
imageID	string	M	The unique identifier of the Item.
url	string	M	The URL of the Item.

ItemReport

Parameter	Type	M/O	Description
itemId	string	M	The unique identifier of the Item.
reporterId	string	O	The unique identifier of the User that reported Item.
reportId	string	M	The unique identifier of the Item report.
reportedDate	string	M	The date when the Item was reported.
reportStatus	string	M	The status of the report. Possible values: `pending`, `accepted`, `declined`, `automaticallyDeclined`.
reportQueues	string[]	M	The report categories. Possible values available through the Get Report Queues endpoint.
reportAdditionalInformation	string	O	The additional information provided by the User regarding the report.
approvalAdditionalInformation	string	O	The additional information provided by the Admin regarding the closure.
reportProcessedDate	string	O	The date when the Item report was processed.
approverId	string	O	The unique identifier of the Admin that processed the report.
downloadCount	number	M	The number of times the report was downloaded in CSV format.
downloadLastDate	string	O	The date when the report was last downloaded in CSV format.
itemMetadata	object	O	The metadata of the Item that was reported.
itemMetadata.rawPositivePrompt	string	O	The raw positive prompt of the Item.
itemMetadata.filteredPositivePrompt	string	O	The filtered positive prompt of the Item.
itemMetadata.rawNegativePrompt	string	O	The raw negative prompt of the Item.
itemMetadata.filteredNegativePrompt	string	O	The filtered negative prompt of the Item.
itemMetadata.workflowUsed	string	O	The workflow that was used to generate the Item.
itemMetadata.modelId	string	O	The unique identifier of the AI generation Model.
itemMetadata.url	string	O	The URL of the Item.
authorMetadata	object	O	The metadata of the User who generated the Item.
authorMetadata.userId	string	O	The unique identifier of the User.
authorMetadata.userEmail	string	O	The email of the User.
authorMetadata.username	string	O	The username of the User.
authorMetadata.flaggedItemsCount	number	O	The number of flagged Items (accepted reports) of the User.
authorMetadata.abuse	number	O	Whether the User is flagged as abusive.
authorMetadata.isDisabled	boolean	O	Whether the User is disabled.

Model

Parameter	Type	M/O	Description
modelID	string	M	The unique identifier of the AI generation Model.
name	string	M	The human-readable name of the AI generation Model.
description	string	M	The description of the Model.
mediaType	string	M	The media type of the Items generated by the Model. Possible values: `StaticImage`, `AnimatedImage`, `Video`, `Text`, `Music`, `Other`, `Unknown`.
minTier	number	M	The minimum User PRO tier needed to use the Model.
tier0Concurrent	number	M	The number of concurrent Items that can be generated by the User with PRO tier 0 (no PRO tier) with the Model.
tier1Concurrent	number	M	The number of concurrent Items that can be generated by the User with PRO tier 1 with the Model.
tier2Concurrent	number	M	The number of concurrent Items that can be generated by the User with PRO tier 2 with the Model.
positiveTokens	string[]	M	The list of positive tokens that are included in the Model (?).
negativeTokens	string[]	M	The list of negative tokens that are included in the Model (?).
sampleImages	ImageThumbnail[]	M	An array of sample images used to showcase the Model's capabilities.
minSteps	number	M	The minimum number of steps supported by the Model.
maxSteps	number	M	The maximum number of steps supported by the Model.
allowedWidths	number[]	M	The list of allowed widths (in pixels) for Items generated with the Model.
allowedHeights	number[]	M	The list of allowed heights (in pixels) for Items generated with the Model.
maxResolution	number	M	The maximum resolution (in pixels, calculated as width * height) for Items generated with the Model.
defaultResolution	number[]	M	The default resolution (in pixels, shown as `[width, height]`) for Items generated with the Model.
allowedSamplers	string[]	M	The list of allowed samplers for Items generated with the Model.
defaultSampler	string	M	The default sampler for Items generated with the Model.
minCfgScale	number	M	The minimum CFG scale supported by the Model.
maxCfgScale	number	M	The maximum CFG scale supported by the Model.
supportsVariations	boolean	M	Whether the Model supports variations.
registrationWall	boolean	M	Whether the User is required to sign up before using the Model.
defaultFaceFix	boolean	M	The default state of face fix for Items generated with the Model.
wikiURL	string	O	The URL of the Model's guide on the wiki page (e.g., https://wiki.sexy.ai/en/ModelGuides), if any.

Prompt

Parameter	Type	M/O	Description
positivePrompt	string	M	The positive component of the prompt.
negativePrompt	string	O	The negative component of the prompt.
userID	string	O	The unique identifier of the User that created the prompt.

BillingPlan

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the Billing Plan.
name	string	M	The name of the Billing Plan.
description	string	O	The description of the Billing Plan.
features	string[]	O	The list of features that are included in the Billing Plan.
mainBenefits	string[]	O	The list of main benefits that are included in the Billing Plan.
prices	BillingPlanPrice[]	M	The price of the Billing Plan.
tier	number	M	The target User PRO tier related to the current Billing Plan.

BillingPlanPrice

Parameter	Type	M/O	Description
name	string	O	The name of the Billing Plan Price. Generally only used for display purposes on discounts.
type	string	M	The type of the Billing Plan. Possible values: `base`, `discount`, `bundle`, `trial`, `free`, `giftcard`, `other`, `none`.
period	string	M	The period of the Billing Plan. Possible values: `daily`, `monthly`, `yearly`, `lifetime`, `none`.
currency	string	M	The currency of the Billing Plan. Possible values: `USD`, `EUR`, `GBP`, `CAD`, `AUD`, `JPY`, `CHF`, `CNY`, `BTC`, `ETH`, `SOL`, `BNB`, `MATIC`, `USDC`, `USDT`, `none`.
currencyType	string	M	The BillingPlanPriceTypetype of the currency. Possible values: `fiat`, `crypto`, `other`, `none`.
value	number	M	The value of the Billing Plan.
trialDays	number	O	The number of trial days (if the Billing Plan is a trial).
paymentProviders	BillingPlanPaymentProvider[]	M	The list of payment providers that are supported by the Billing Plan.

BillingPlanPaymentProvider

Parameter	Type	M/O	Description
paymentProvider	string	M	The name of the payment provider. Possible values: `arkpay`, `boosty`, `ccbill`, `epoch`, `g2a`, `helio`, `nmi`, `patreon`, `paypal`, `stripe`, `giftcard`, `admin`, `whitelist`, `other`, `none`.
paymentLabel	string	O	A human-readable label of the payment provider, with may be used in a payment page/button (e.g., "Pay with Crypto").
paymentUrl	string	M	The URL of the external payment page.

LogEntry

Parameter	Type	M/O	Description
timestamp	number	O	The timestamp (UNIX epoch, in milliseconds) of the Log Entry.
message	string	M	The message of the Log Entry.
level	string	O	The level of the Log Entry. If not provided, defaults to `info`. Possible values: `info`, `warn`, `error`.
apiSubscope	string	O	The subscope of the API/process that produced the Log Entry. Used to group similar Log Entries.
httpMethod	string	O	If the Log Entry corresponds to an HTTP request, the HTTP method of the request that produced the Log Entry. Possible values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
httpPath	string	O	If the Log Entry corresponds to an HTTP request, the HTTP path of the request that produced the Log Entry. It corresponds to the API name in most cases (e.g. `getModels`, `getSelfUser`, etc.).
httpUrl	string	O	If the Log Entry corresponds to an HTTP request, the HTTP URL of the request that produced the Log Entry. It corresponds to the full URL of the request.
errorName	string	O	If the Log Entry represents an error, the name of the error that produced the Log Entry (i.e., `error.name`).
errorMessage	string	O	If the Log Entry represents an error, the message of the error that produced the Log Entry (i.e., `error.message`).
errorStack	string	O	If the Log Entry represents an error, the stack trace of the error that produced the Log Entry (i.e., `error.stack`).

FileMetadata

Parameter	Type	M/O	Description
id	string	M	The unique identifier of the File.
publicUrl	string	M	The public URL to access the File.
fileName	string	M	The name of the File.
contentType	string	M	The MIME type of the File.
fileSize	number	M	The size of the File in bytes.
createdDate	number	M	The timestamp (as ISO 8601 string) of when the File was created.
checksum	string	M	The checksum of the File.
checksumAlgorithm	string	M	The checksum algorithm of the File. Possible values: `md5`, `sha1`, `sha256`, `sha512`.
ownerId	string	O	The unique identifier of the User that created the File.

WorkflowTemplate

Parameter	Type	M/O	Description
name	string	M	The unique identifier of the Workflow Template.
deployments	string[]	M	The list of environments where the Workflow is deployed. Possible values: `a2stage`, `a2prod`.
parameters	WorkflowTemplateParameter[]	M	The list of parameters supported by the Workflow Template.
workflowTemplateFiles	object	M	The list of files of the Workflow Template. Each file is keyed by its name (as a string) and the value is a WorkflowTemplateFile object.

WorkflowTemplateParameter

Parameter	Type	M/O	Description
name	string	M	The name of the Workflow Template Parameter.
type	string	O	The type of the Parameter.
dataType	string	M	The data type of the Parameter. Possible values: `string`, `number`, `boolean`, `array`, `object`, `file`, `files`, `filesGroup`, `dropdown`.
uiType	string	O	The UI type of the Parameter, used to override the default `dataType`. Use the `dataType` if not provided.
description	string	M	The description of the Parameter.
defaultValue	string	M	The default value of the Parameter. Used when the user does not provide a value throgh `userValue`.
userValue	string	O	The user-provided value of the Parameter.
replaceFromString	string	M	The string that identifies the Parameter within the ComfyUI Workflow.
extraData	any	O	The extra data of the Parameter. Reserved for future use.
isOptional	boolean	M	Whether the Parameter is optional.
min	string	O	The minimum value of the Parameter.
max	string	O	The maximum value of the Parameter.
increment	string	O	The increment value of the Parameter.
optionName	string	M	The option name of the Parameter.
isAlwaysVisible	boolean	M	Whether the Parameter is always visible.
isHidden	boolean	M	Whether the Parameter is hidden.
fileGroup	string	O	The file group of the Parameter.
fileGroupDestination	string	O	The file group destination of the Parameter.
dropdownItems	string[]	O	The dropdown items of the Parameter.

WorkflowTemplateFile

Parameter	Type	M/O	Description
fileNames	string[]	M	An array of file names associated with the Workflow Template.
supportFileType	string	M	The file type.

WorkflowStateObject

Parameter	Type	M/O	Description
_id	string	M	The internal unique identifier of the Workflow State.
publicId	string	O	The unique identifier of the Workflow. This is generally referred to as `workflowId`.
runParamaters	object	O	The parameters used to run the Workflow.
runParamaters.publicId	string	O	The unique identifier of the Workflow. This will usually be `null` here.
runParamaters.workflowTemplateName	string	O	The name of the Workflow Template used to run the Workflow.
runParamaters.parameters	WorkflowRunParameter[]	O	The list of parameters used to run the Workflow.
isStarted	boolean	M	Whether the Workflow has started running.
isComplete	boolean	M	Whether the Workflow has completed running.
isError	boolean	M	Whether the Workflow has encountered an error.
errorMessage	string	O	The error message encountered during the Workflow execution.
outputFiles	WorkflowOutputFileEntry[]	O	An array of file entries generated by the Workflow.
log	string[]	O	An array of log messages generated by the Workflow.
workflowJsonString	string	O	The Workflow JSON string used to run the Workflow.
state	string	O	The state of the Workflow. Possible values: `running`, `completed`, `error`.
startTime	string	M	The timestamp (as ISO 8601 string) the Workflow started running.
endTime	string	M	The timestamp (as ISO 8601 string) the Workflow completed running.
api2userEmail	string	O	The email of the user who ran the Workflow (if applicable).
itemIds	string[]	M	The unique identifiers of the Items generated by the Workflow.

WorkflowRunParameter

Parameter	Type	M/O	Description
name	string	M	The name of the Parameter.
value	string	M	The value of the Parameter. This will always be the stringified value even if the Parameter is a number, boolean, etc.

WorkflowOutputFileEntry

Parameter	Type	M/O	Description
note	string	O	A note about the file.
fileName	string	O	The name of the file.
downloadURL	string	O	The URL to download the file.
isMainOutput	boolean	M	Whether this is the main output of the Workflow.
height	number	M	The height of the file.
width	number	M	The width of the file.
type	string	O	The MIME type of the file.

PaginationMetadata

Parameter	Type	M/O	Description
paginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Items will be returned if their reference timestamp is less than this value. This is the value that was passed in the request. Defaults to 0.
nextPaginationIndex	string	O	A stringified integer that represents a timestamp (UNIX epoch, in milliseconds). Use this value in the `paginationIndex` parameter of the next request.
reversePagination	boolean	O	Whether the pagination should be handled in reverse order. This is the value that was passed in the request.
skipCount	number	O	The number of Items skipped in the current request.
limit	number	O	The maximum number of Items returned in the current request.
count	number	O	The number of Items returned in the current request. This corresponds to the length of the array in the response.
totalCount	number	O	The estimated total number of Items in the current request. Only returned in certain circumstances.
proLimitHit	boolean	O	Whether the number of Items returned in the current request is less than the actual number of Items due to a limitation imposed to non-Premium Users. Only returned in certain circumstances.

Annex: Errors

The AIMG API uses the following HTTP error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- You are not signed in.
403	Forbidden -- You are not allowed to access the requested resource.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
408	Request Timeout -- Your request timed out.
409	Conflict -- You tried to create a resource that already exists.
410	Gone -- The resource requested has been removed from our servers.
429	Too Many Requests -- You're requesting too many resources! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

All API responses usually include a hasError boolean flag that indicates whether the response represents an error, even if the HTTP status code is 200.

When hasError is true, the response also includes the errorMessage string property, containing a description of the error. It may sometimes contain the errorCode integer property, as well. payload is always present but usually null on errors.

The errorMessage property is a human-readable description of the error. It is usually safe to display on the front-end, even though it may be usually better to display a custom and more informative error message built by the front-end.

Annex: Administration APIs

Some APIs may only be used by Admins, or may have different behaviors if used by authorized Admins.

Currently, the identification of an Admin is done by providing a personal X-Administration-Key header in the request. In the future, this will be implemented using the X-Session-ID header of the current front-end session and through a RBAC (Role-Based Access Control) mechanism.

This chapter lists the Administration APIs that are available in the AIMG API.

User Management
Premium Membership Management
Image Management
Technical

Annex: Public Items Approval Workflow

The AIMG API supports the concept of "Public Items", which are items that are available for all Users.

In general, public Items can be of two kinds:

Actual Items, as in the case of images or videos.
Collections, as in the case of Folders.

Items (type 1) must undergo an explicit approval process before they can be published. Folders (type 2) are dynamically made public depending on their content and limitedly to the public Items contained in them, and do not require explicit approval.

Once an Item is approved, it can be made public by the owner of the Item. At any time, an Item can be made private again by the owner.

Here's the general state diagram of the approval process:

Step 1: Default State and Beginning of the Approval Workflow

Given a private Item, generally identified by the imageID of the Item, the initial and default state for such Item is defined as follows:

publicApprovalStatus is set to none (type: string).
isPublic is set to true (type: boolean).

These two values can be checked at any time using the getItem, getItemDetails or getMyCreations endpoints.

The User can submit the Item for approval by setting publicApprovalStatus to pending using the setItemProperties endpoint. A User can only have a maximum of 50 approval request in state pending at any time.

At this point in time, trying to set isPublic to true will not have any effect on the Item.

Additionally, at any point in time, trying to set publicApprovalStatus to approved or rejected will also not have any effect on the Item.

Step 2: Pending Approval and Approval Process

Once an Item's publicApprovalStatus is set to pending, the Item will be made available to Admins for approval.

At any time during this phase, as long as the Item is not already approved (i.e., publicApprovalStatus is still pending), the User can withdraw the approval request by setting publicApprovalStatus back to none using the setItemProperties endpoint.

Admin Actions

The Admin UI should query the MongoDB images collection for Items that have publicApprovalStatus set to pending and show them to the Admins together with the relevant information.

In the Admin UI, Admins can review each Item and:

Approve it, by setting publicApprovalStatus to approved and isPublic to true.
Reject it, by setting publicApprovalStatus to rejected and isPublic to false.

Both approved and rejected states are final, and irreversible by the User. At any time afterward, if the User tries to set publicApprovalStatus to any other value using the setItemProperties endpoint, it will fail.

Step 3: Item Visibility once Approved

Once an Item's publicApprovalStatus is set to approved, it will automatically become public as long as the Item's isPublic is set to true (the Admin UI will set it to true automatically as soon as the Item is approved).

The User will not get notified that the Item has been approved, and will be able to check if the Item is public by checking isPublic through the getItem, getItemDetails or getMyCreations endpoints.

At this point in time, isPublic becomes editable by the User using the setItemProperties endpoint. publicApprovalStatus, on the other hand, is not editable anymore and attempting to set it to any value will fail.

If, at any time, the User sets isPublic to false, the Item will become private. Since the Item is already approved, the User will be able to turn it public again by setting isPublic to true without having to go through the approval process again.

Annex: Rejecting an Item after Approval

The Admin UI should allow Admins to reject an Item after it has been approved.

The Admin UI should query the MongoDB images collection for Items that have publicApprovalStatus set to approved and show them to the Admins together with the relevant information (in a different tab than the one containing the pending Items).

Admins can then review each already approved Item and reject it, by setting publicApprovalStatus to rejected and isPublic to false.

Introduction

API Endpoints

Pagination

External Login Providers

HTTP Request

Path Parameters

Body Parameters

HTTP Response

User Management

Create User

HTTP Request

Body Parameters

HTTP Response

Authenticate User

HTTP Request

Body Parameters

HTTP Response

Sign Out User

HTTP Request

Body Parameters

HTTP Response

Request OTP Code for User

HTTP Request

Body Parameters

HTTP Response

Get Self User

HTTP Request

Query Parameters

HTTP Response

Set Self User Properties

HTTP Request

Body Parameters

HTTP Response

Set Self User Profile Picture

HTTP Request

Body Parameters

HTTP Response

Set Profile Picture Banned

HTTP Request

Headers

Body Parameters

HTTP Response

Set User Additional Information

HTTP Request

Headers

Body Parameters

HTTP Response

Get User Key-Value Pair

HTTP Request

Query Parameters

HTTP Response

Set User Key-Value Pair

HTTP Request

Body Parameters

HTTP Response

Delete User Key-Value Pair

HTTP Request

Query Parameters

HTTP Response

Get User

HTTP Request

Headers

Query Parameters

HTTP Response

Generate a Strong Password

HTTP Request

HTTP Response

Delete User

HTTP Request

Headers

Query Parameters

HTTP Response

Set User Abuse Level

HTTP Request

Headers

Body Parameters

HTTP Response

Premium Membership Management

Get Billing Plans

HTTP Request