SDK Reference
Last updated
Was this helpful?
Last updated
Was this helpful?
This reference guide covers the ChainGPT AI NFT Generator JavaScript/TypeScript SDK, detailing its installation, configuration, and all major functions. It focuses on using the SDK in Node.js or web applications (via bundlers) to generate AI-driven images and mint them as NFTs. (For a high-level overview of the AI NFT Generator’s capabilities, see the ; for HTTP endpoints, see the REST API Reference.)
The SDK methods documented here provide a convenient wrapper around the ChainGPT AI NFT Generator API, handling lower-level details like HTTP requests and file handling. Each function is explained with parameters, return values, and code examples, including both educational snippets (with commentary) and production-ready snippets for quick copy-paste usage.
Install the SDK Package: The ChainGPT NFT SDK is available as an npm package @chaingpt/nft. Use npm or Yarn to add it to your project:
This will install the SDK and its TypeScript type declarations.
Import and Initialize the SDK: The SDK exports an Nft class. Import this class and instantiate it with your API key (obtained from the ChainGPT developer dashboard):
Configuration: Only an apiKey is required to start. The SDK handles authentication using this key for all calls. By default, the SDK will use ChainGPT’s hosted API endpoints. No additional setup is needed beyond providing a valid API key.
The SDK allows you to generate AI art images from text prompts without immediately minting them as NFTs, using the generateImage() method. This is useful if you want to preview or use the AI-generated image first (e.g. for user approval) before committing to an on-chain mint.
generateImage(options)Description: Generates an image from a text prompt using ChainGPT’s AI model, returning the image data. No blockchain interaction occurs in this step – it strictly performs image generation based on the given prompt and parameters. (If you want to directly prepare an NFT for minting, see generateNft() below.)
Parameters: (all passed in a single options object)
prompt (string, required) – The text prompt describing the desired image. This can be any creative description of the image you want.
model (string, required) – The name of the AI model to use for generation. Supported models include velogen, nebula_forge_xl, VisionaryForge, and Dale3. Each model has a different style or aesthetic (e.g. photorealistic, anime, 3D, etc.).
enhance (string, optional) – Image enhancement/upscaling level. Use "1x" for single enhancement, "2x" for double enhancement, or omit/empty for no enhancement. Enhancement can improve image resolution/quality, but is only supported by certain models (velogen, nebula_forge_xl, VisionaryForge).
steps (number, optional) – The number of diffusion/refinement steps for image generation. More steps can yield more detailed images at the cost of time. Each model supports a range: e.g. velogen supports 1–4 steps (default 2), nebula_forge_xl up to 50 (default 25). If not provided, the model’s default is used.
width (number, optional) – The width of the resulting image in pixels.
height (number, optional) – The height of the resulting image in pixels.
Returns: A Promise that resolves to an object containing the generated image data. The image data is typically provided as a binary buffer or byte array for the image (in JPEG format by default, which you can save as a .jpg file). You may access the raw bytes and save or manipulate the image as needed.
Example – Generate an image and save to a file (with explanations):
In this example, we generate a 1024×1024 image using the velogen model with a given prompt. The result’s data property holds the image bytes, which we write to a JPEG file. After running this code, the file generated-image.jpg will contain the AI-generated artwork.
Example – Production-ready snippet:
This minimal snippet shows a straightforward use of generateImage to get an image for further use. In a real application, you might directly send imgRes.data.data as a response (in a web server) or display it in a frontend app (after encoding to Base64 or creating an object URL, etc.).
The core purpose of the ChainGPT NFT SDK is to generate images and mint them as NFTs on a blockchain. The SDK provides two approaches:
Synchronous NFT generation – generate the image (wait until complete) then mint it, suitable for one-off NFTs or immediate results.
Asynchronous (Queued) NFT generation – start the generation and return immediately, allowing you to handle many generation jobs in parallel or off-load long-running tasks, then mint when ready.
In both cases, the minting step is performed via the mintNft() method once the image is generated. Below are the relevant SDK functions and how to use them.
generateNft(options) – Synchronous GenerationDescription: Generates an NFT image from a prompt with the intention to mint it. This call will handle the AI image creation and prepare the NFT metadata, returning when the image is ready. You will typically call mintNft() afterwards to actually mint the NFT on-chain. Use this method for single NFT generation flows where the user or app can wait for the image to finish (typically 30–60 seconds). Under the hood, this wraps an API call that combines image generation and NFT metadata creation in one step.
Parameters: (passed in an options object)
**All image generation parameters from **generateImage() – prompt, model, enhance, steps, height, width are used in the same way as in generateImage() (see above) to control the AI generation.
walletAddress (string, required) – The public wallet address that will own the minted NFT. This is the address to which the NFT will be sent after minting. It should be a valid address on the target blockchain network.
chainId (number, required) – The blockchain network ID where the NFT will be minted. ChainGPT supports 25+ chains including Ethereum, BNB Chain, Polygon, Arbitrum, Avalanche, Tron, etc. (see Overview for the full list). For example: 1 for Ethereum Mainnet, 56 for BSC Mainnet, 137 for Polygon, etc. You can use the getChains() method (documented below) to retrieve a list of supported chain IDs at runtime.
(No explicit name/description********** here – those will be provided in the mintNft() call instead.)
Returns: A Promise resolving to an object with the generated NFT data. This includes the image data (similar to generateImage result) and a collectionId identifier for the generated NFT content. The collectionId is a unique ID referencing this generation task / NFT draft on the ChainGPT platform. You will use this ID to mint or check status later. The promise resolves only after the image generation is complete (synchronous behavior).
Example – Generate an NFT then mint it (with explanations):
In this example, we first call generateNft() with the prompt and required parameters. Once the promise resolves, we have an image ready and a collectionId that identifies this generated NFT data. We then call mintNft() with that ID and provide a human-friendly name, description, and symbol for the NFT. The SDK handles the on-chain minting transaction: the NFT will be minted on BSC Testnet (chain 97) to the specified wallet address. The mintResult may include details of the mint operation (such as transaction hash or token ID, depending on the implementation).
Example – Production snippet (generate then mint):
This snippet omits commentary for brevity. It generates an NFT on BNB Chain (chainId 56) for the given wallet, then immediately mints it with a name and symbol. In a real app, you may want to handle errors around these calls or update your UI state between generation and minting steps.
generateNftWithQueue(options) – Asynchronous/Queued GenerationDescription: Initiates an NFT generation task asynchronously (non-blocking). Instead of waiting for the image to finish generating, this function returns quickly with a collectionId that represents the queued job. The actual image generation happens in the background on ChainGPT’s servers. You can then poll the status of the job using getNftProgress() and mint the NFT when ready. This approach is ideal for batch generation or handling high volumes, as you can queue up multiple NFTs in parallel without halting your code flow.
Parameters: Same as generateNft() above – you must provide prompt, model, any optional generation settings (enhance, steps, height, width), plus the target walletAddress and chainId for the eventual mint.
Returns: A Promise that resolves to an object containing at least a collectionId for the queued generation request. The image will not be available immediately. You will use the collectionId to track progress and later mint the NFT. The function returns as soon as the generation task is successfully queued on the server.
Example – Queue an NFT generation and check progress (with explanations):
In this example, we fire off an NFT generation using generateNftWithQueue(). We immediately get a collectionId for the job and then enter a loop, using getNftProgress() to poll the job’s status. Once the progress status indicates completion (100% or "completed"), we call mintNft() with the same collectionId to mint the NFT on-chain. The polling interval here is 5 seconds, but in a real application you might use a longer interval or a webhook/callback mechanism if provided. You can also queue many jobs and poll each in turn or in parallel, enabling scalable generation of large NFT collections.
Example – Production snippet (queue generation):
The above snippet demonstrates the basic queued call. After this, you would typically use getNftProgress() later and then mintNft(). For brevity, those parts are omitted here (see the detailed example above for the full flow).
getNftProgress(options) – Check Generation ProgressDescription: Checks the status of an ongoing NFT generation job that was started with generateNftWithQueue(). It returns the progress or completion status of the image generation. This is typically used in a loop or interval to poll for completion if you are not using a callback system.
Parameters:
collectionId (string, required) – The unique ID of the NFT generation job to query. This is the ID returned by generateNftWithQueue() (or generateNft() as well, if you choose to poll even for synchronous calls).
Returns: A Promise resolving to an object containing progress information. The exact fields might include a percentage or status indicator. For example, you may receive { progress: 100, status: "completed", ... } when done. Before completion, it might show a lower percent or a status like "processing". Once the generation is finished, you can proceed to mint the NFT. If an invalid ID is provided or the job failed, an error or failure status will be returned.
Example – Check progress (basic usage):
Production snippet:
Typically, you will call this repeatedly until completion, as shown in the more detailed example under generateNftWithQueue(). Use this method to inform users about wait times or to trigger the next step once the image is ready.
mintNft(options) – Minting the Generated NFTDescription: Mints an NFT on the blockchain for a previously generated image/metadata (identified by a collectionId). This completes the NFT creation process by writing the token to the blockchain. You should call this after generating the NFT via either generateNft() or generateNftWithQueue(). The method also allows you to specify the NFT’s metadata details like name, description, and symbol.
Parameters:
collectionId (string, required) – The ID of the generated NFT content to mint. This comes from a prior call to generateNft/generateNftWithQueue.
name (string, required) – The name of the NFT to mint. This could be the title of the artwork or a unique name for this token.
description (string, optional) – A description for the NFT’s metadata (e.g. details about the image, project, etc.). This will be included in the token’s metadata JSON.
symbol (string, optional) – The symbol or shorthand for the NFT collection. If the minting involves deploying a new NFT collection (contract), this symbol will be used for the collection (similar to a ticker symbol). For one-off mints it can be a short identifier.
Returns: A Promise resolving to an object containing the result of the mint operation. On success, this might include transaction details, the minted token ID, or a confirmation that the NFT has been minted. If the SDK handles the blockchain transaction internally, the promise will only resolve when the transaction is confirmed or at least submitted. (Refer to ChainGPT’s docs for specifics on whether this auto-deploys a new contract or mints on an existing one – the SDK abstracts those details).
After calling mintNft(), the image generated by the given collectionId is now an actual NFT on the specified blockchain, owned by the provided wallet address. The NFT’s metadata (name, description) is set as given.
Example – Minting an NFT (immediate usage):
Production snippet:
In practice, you would incorporate error handling to catch any issues during minting (network errors, insufficient funds if any gas needed, etc.). See Error Handling for how to catch NftError exceptions from this call.
ChainGPT’s NFT Generator provides a Prompt Enhancement feature to help users get better image generation results. The SDK exposes this via the enhancePrompt() method, which takes a raw prompt and returns a more detailed or refined version of it. This can be useful if you want to assist users in crafting prompts or to programmatically improve prompt inputs before generating images.
enhancePrompt(options)Description: Enhances or refines a given text prompt by adding more details, context, or creative wording. The result is a new prompt that is likely to produce a higher-quality or more imaginative image from the AI. (The platform may use its own AI logic to do this enhancement.)
Parameters:
prompt (string, required) – The original prompt text to enhance. This should be a short description of an image or concept.
Returns: A Promise resolving to an object containing the enhanced prompt. The returned prompt may include additional adjectives, context, or formatting. You can directly use the enhanced prompt with generateImage or generateNft to potentially get better results.
Example – Enhance a prompt (with explanations):
In this example, a simple prompt "a small cottage by the lake" might be automatically expanded to something like "a cozy small cottage by the misty lake at sunrise, photorealistic, high detail" (the actual output will vary). Using the enhanced prompt in generateImage or generateNft could yield more vivid results.
Production snippet:
This shows how you might call enhancePrompt in production – for example, to implement a "Suggest improvements" button for user-provided prompts. The output prompt (accessible as enhanced.prompt or a similar field) can then be shown to the user or used directly.
(The SDK may also offer a “Surprise Me” or random prompt generator feature as hinted in the overview, but the primary prompt utility in the SDK is enhancePrompt.)
If you need to know which blockchains are supported or get their identifiers (especially to let users choose a network for minting), the SDK provides a method to fetch the list of supported chains.
getChains(includeTestnet)Description: Returns a list of blockchain networks (chain IDs) supported by the NFT generator. You can choose to include test networks or not. This is useful for populating network selection dropdowns or validating a chainId before attempting a mint.
Parameters:
includeTestnet (boolean, optional) – If false (default), returns only mainnet chains. If true, test networks are included as well. Use true if you need testnet IDs for development.
Returns: A Promise resolving to an array of chain information. Each entry will typically include at least a chain ID (number) and possibly a name or network identifier. For example, an entry might be { chainId: 1, name: "Ethereum Mainnet" }, { chainId: 56, name: "BSC Mainnet" }, or { chainId: 97, name: "BSC Testnet" }, etc. The exact structure can be determined by inspecting the returned object. All networks supported by ChainGPT’s NFT Generator will be listed.
Example – Get supported chains:
This might output a list such as 1 Ethereum, 56 BNB Chain, 137 Polygon, ... etc., covering all mainnet networks available. If you call getChains(true), you will see testnets (e.g., Ropsten, Goerli for Ethereum if supported, Mumbai for Polygon, etc.) in the list as well.
Production snippet:
This quickly retrieves the full list of supported chain IDs (including test networks). You might use this to validate user choices or to know if a particular chainId is currently supported by ChainGPT’s service.
ChainGPT’s NFT Generator mints tokens using its own smart contract (often a factory or template contract). If you need to interact with the NFT contract directly (for example, to call the mint function manually or to integrate with web3 libraries for events), you can retrieve the contract’s ABI (Application Binary Interface) via the SDK.
abi()Description: Fetches the ABI for the ChainGPT NFT Mint Factory contract. The ABI is a JSON specification of the contract’s functions and events, which is required to create a web3 contract instance (e.g., with ethers.js or web3.js) to call contract methods or decode logs.
Parameters: None.
Returns: A Promise that resolves to the ABI data (likely an array of JSON fragments describing each function/event). This ABI corresponds to the smart contract that the SDK uses under the hood to mint NFTs. With this, developers can instantiate the contract in their own web3 context if needed.
Example – Retrieve contract ABI:
This will output the number of entries in the ABI (functions, events). You could then do something like:
Now contract is a read-only instance (or if you have a signer, read-write) of the NFT contract, and you can call functions or listen to events as defined by the ABI.
Production snippet:
Typically, you might not need to call abi() unless you are doing advanced integrations. The SDK’s own methods (generateNft, mintNft, etc.) will handle contract interactions for you. But the option is there for completeness or custom use cases.
(This section provides reference details on the supported models, enhancements, and image formats in the ChainGPT NFT Generator SDK.)
Supported AI Models: The following model identifiers can be used for the model parameter when generating images or NFTs:
velogen – for realistic or general-purpose image generation.
nebula_forge_xl – for high-resolution, detailed imagery.
VisionaryForge – for creative/artistic styles (e.g., concept art).
Dale3 – (integration of OpenAI’s DALL·E 3 or similar) for varied art generation.
Each model may have different strengths or styles (e.g., Dale3 might excel at certain creative compositions). You can experiment with different models to achieve the desired visual style.
Image Formats: Generated images are returned in a binary format that can be saved as common image types. By default, images are in JPEG format (as indicated by the .jpg usage in examples) when using the provided API endpoints. The SDK does not currently provide an option to choose the file format (such as PNG) via parameters, so you can assume JPEG output. If a different format is needed, you may convert the image bytes using an image processing library after retrieval.
Enhancement (enhance******************** parameter): As noted, you can request upscaling enhancements:
"1x" – Single enhancement (upscale once).
"2x" – Double enhancement (upscale twice for even higher resolution).
Only certain models support enhancement (currently velogen, nebula_forge_xl, VisionaryForge). If you use enhance on an unsupported model, the enhancement may be ignored. Using enhancement will yield larger image dimensions (roughly doubling the resolution in each step).
Resolution and Aspect Ratios: Each model has preset supported resolutions:
Velogen: Base outputs: 512Ă—512 (square), 768Ă—512 (landscape), 512Ă—768 (portrait). With 2Ă— enhancement: 1920Ă—1920, 1920Ă—1280, 1280Ă—1920.
Nebula Forge XL: Base outputs: 1024Ă—1024, 1024Ă—768, 768Ă—1024. With upscaling: 1536Ă—1536, 1536Ă—1024, 1024Ă—1536.
VisionaryForge: Base outputs: 1024Ă—1024, 1024Ă—768, 768Ă—1024. With upscaling: 1536Ă—1536, 1536Ă—1024, 10
Dale3: (Not explicitly listed in the SDK docs, but it likely supports standard square sizes such as 1024×1024. You may refer to ChainGPT’s documentation for any specifics.)24×1536.
When specifying height and width, choose one of the supported combinations above for the model you use. If you choose a non-supported resolution, the API may return an error or adjust to the nearest valid size. For simplicity, common squares (512 or 1024) are safe across models.
Default Values: If certain optional parameters are omitted:
enhance: no enhancement (equivalent to not upscaling).
steps: uses model default (e.g., 2 for velogen, 25 for nebula_forge_xl).
height/width: likely defaults to the model’s base square resolution (e.g., 512×512 or 1024×1024 depending on model). It’s recommended to specify them explicitly to control the aspect ratio.
Use these references to fine-tune your image generation. For instance, if you want a large portrait image, using model: "nebula_forge_xl", enhance: "2x", width:1024, height:1536 would produce an upscaled portrait orientation result. If unsure, start with a base model and resolution (e.g., 512Ă—512 velogen) and then adjust parameters for higher quality.
The ChainGPT NFT SDK provides a structured way to handle errors. Network issues, invalid requests, or API errors will result in the SDK throwing an instance of Errors.NftError. You should catch these errors in your async functions to handle them gracefully.
Error type: Errors.NftError – This error object (a class instance) includes a message describing the issue (e.g., an HTTP error status or a message from the API). It may also include additional data or codes from the response.
How to catch: Use a try...catch around SDK calls. In the catch, check if error instanceof Errors.NftError to confirm it’s an SDK error and not a different exception.
Example – Error handling pattern:
In this snippet, if the generateNft call fails (for example, due to an invalid API key, network timeout, or a 400/500 HTTP error from the API), the catch block will execute. The error message (error.message) may contain a human-readable explanation of what went wrong. Always handle errors especially for network calls like generation or minting, to ensure your application can inform the user or retry as needed.
Common error scenarios:
Authentication failure: If your API key is wrong or expired, you’ll get an NftError (likely with a 401/403 status message).
Invalid parameters: If you request an unsupported image size or missing required fields, the API may return an error (400 Bad Request), resulting in an NftError.
Generation failure: In rare cases the AI might fail to generate an image; the API could return an error or a status indicating failure for that job.
Network issues: If the SDK cannot reach the server, it will throw an NftError (with a message like network error or timeout).
By catching NftError, you can distinguish errors coming from ChainGPT’s API versus other exceptions. You can also use the error information to decide retries or user messages. The SDK’s error handling mechanism ensures you don’t have to manually parse HTTP responses – it consistently throws NftError for anything that isn’t a normal successful response.
The ChainGPT NFT SDK is written in TypeScript and comes with full type declarations. This means you get autocompletion and type checking out-of-the-box when using the SDK in a TypeScript project or any editor with TypeScript definitions.
All methods (generateImage, generateNft, etc.) have typed function signatures. The expected input object shape and return types are defined, which helps catch mistakes (for example, forgetting a required field or using the wrong type for a parameter).
The Nft class constructor options (apiKey etc.) are typed as well. You can import types if needed for your own definitions.
Using ESM/TypeScript import:
In the above TypeScript example, your IDE will guide you with the correct parameter names and types for generateNft. The return type result will also be known (you can inspect its type, likely something like NftResponse with a .data field).
Typing for Errors: The Errors.NftError class is also available for type checking. You can do catch (error: any) { if (error instanceof Errors.NftError) { ... } } – TypeScript will then infer error as NftError inside that block, allowing you to access any specific properties it has.
Because of the included d.ts files, you do not need to install any additional @types packages for this SDK. Everything is bundled in @chaingpt/nft by default.
Happy building with ChainGPT’s NFT SDK!