# Python

## ChainGPT AI NFT Generator SDK Documentation

The ChainGPT AI NFT Generator SDK provides a comprehensive suite of tools to create, manage, and prepare NFTs for minting. This includes enhancing prompts, generating images (synchronously and asynchronously), tracking generation progress, retrieving minting metadata, and querying supported blockchains and contract ABIs.

### Table of Contents

1. Installation
2. Quick Start
3. SDK Initialization
4. NFT Service Overview
5. NFT Service Methods
   * enhance\_prompt()
   * generate\_image()
   * generate\_nft\_queue()
   * get\_progress()
   * mint\_nft\_metadata()
   * get\_chains()
   * get\_abi()
6. Data Models & Types
7. Enums Reference
8. Error Handling
9. Complete Example
10. Best Practices
11. New Features

***

### Installation

Install the ChainGPT SDK via pip:

```bash
pip install chaingpt
```

Or add to your `requirements.txt`:

```bash
chaingpt>=1.1.4
```

For development with environment variables:

```bash
pip install python-dotenv  # Optional for .env file support
```

***

### Quick Start

Here's a minimal example to get you started:

```python
import asyncio
from chaingpt.client import ChainGPTClient
from chaingpt.models import GenerateImageRequestModel, NFTImageModel

async def quick_example():
    client = ChainGPTClient(api_key="YOUR_API_KEY")
    
    # Generate an image synchronously
    request = GenerateImageRequestModel(
        prompt="a dragon in space",
        model=NFTImageModel.VELOGEN,
        height=512,
        width=512
    )
    
    response = await client.nft.generate_image(request)
    
    # Save the image
    with open("dragon.jpg", "wb") as f:
        f.write(bytes(response.data.data))
    
    await client.close()

if __name__ == "__main__":
    asyncio.run(quick_example())
```

***

### SDK Initialization

#### Basic Initialization

```python
import asyncio
from chaingpt.client import ChainGPTClient
from chaingpt.exceptions import ChainGPTError

# Basic initialization
client = ChainGPTClient(api_key="YOUR_API_KEY")

# With environment variable
import os
API_KEY = os.getenv("CHAINGPT_API_KEY")
client = ChainGPTClient(api_key=API_KEY)
```

#### Required Imports

```python
from chaingpt.client import ChainGPTClient
from chaingpt.models import (
    EnhancePromptRequestModel,
    GenerateImageRequestModel,
    GenerateNFTQueueRequestModel,
    MintNFTRequestModel,
    TraitModel,
    TraitValueItemModel,
    NFTImageModel,
    ImageEnhanceOption
)
from chaingpt.exceptions import ChainGPTError, APIError
```

***

### NFT Service Overview

Access the NFT service through the client:

```python
nft_service = client.nft
```

The NFT service provides seven main methods:

* **enhance\_prompt()**: Improve prompts for better image generation
* **generate\_image()**: Create images synchronously (fast preview)
* **generate\_nft\_queue()**: Queue asynchronous NFT generation (high quality)
* **get\_progress()**: Track queued generation progress
* **mint\_nft\_metadata()**: Generate metadata for blockchain minting
* **get\_chains()**: List supported blockchain networks
* **get\_abi()**: Get smart contract ABI

***

### NFT Service Methods

#### enhance\_prompt()

Enhances or refines a text prompt for better image generation results.

**Method Signature:**

```python
async def enhance_prompt(self, request_data: EnhancePromptRequestModel) -> EnhancePromptResponseModel
```

**Parameters:**

| Parameter      | Type                        | Required | Description                              |
| -------------- | --------------------------- | -------- | ---------------------------------------- |
| `request_data` | `EnhancePromptRequestModel` | Yes      | Request containing the prompt to enhance |

**Request Model (`EnhancePromptRequestModel`):**

| Field    | Type  | Required | Description                         |
| -------- | ----- | -------- | ----------------------------------- |
| `prompt` | `str` | Yes      | The text prompt you want to enhance |

**Response Model (`EnhancePromptResponseModel`):**

| Field                 | Type  | Description                         |
| --------------------- | ----- | ----------------------------------- |
| `statusCode`          | `int` | HTTP status code (200 for success)  |
| `message`             | `str` | Response message                    |
| `data.enhancedPrompt` | `str` | The enhanced version of your prompt |

**Example:**

```python
async def enhance_example():
    enhance_request = EnhancePromptRequestModel(prompt="a dragon in space")
    response = await client.nft.enhance_prompt(enhance_request)
    
    if response.statusCode == 200:
        print(f"Original: a dragon in space")
        print(f"Enhanced: {response.data.enhancedPrompt}")
        # Output might be: "A majestic dragon soaring through the cosmic void, 
        # surrounded by stars and nebulae, highly detailed, fantasy art"
```

***

#### generate\_image()

Generates an image synchronously based on the given prompt and parameters. Best for quick previews and testing.

**Method Signature:**

```python
async def generate_image(self, request_data: GenerateImageRequestModel) -> GenerateImageResponseModel
```

**Parameters:**

| Parameter      | Type                        | Required | Description                 |
| -------------- | --------------------------- | -------- | --------------------------- |
| `request_data` | `GenerateImageRequestModel` | Yes      | Image generation parameters |

**Request Model (`GenerateImageRequestModel`):**

| Field                 | Type                 | Required | Default       | Description                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | -------------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`              | `str`                | Yes      | -             | Text prompt for image generation                                                                                                                                                                                                                                                                                                                      |
| `model`               | `NFTImageModel`      | Yes      | -             | AI model to use (see Enums)                                                                                                                                                                                                                                                                                                                           |
| `height`              | `int`                | Yes      | -             | Image height in pixels                                                                                                                                                                                                                                                                                                                                |
| `width`               | `int`                | Yes      | -             | Image width in pixels                                                                                                                                                                                                                                                                                                                                 |
| `steps`               | `int`                | No       | Model default | Number of refinement passes for image generation. Higher values can yield more detailed images at the cost of longer generation time. Each model supports a range: for example, velogen supports 1–4 steps (default \~2), while NebulaForge XL and VisionaryForge support up to 50 (default \~25). If not provided, a model-specific default is used. |
| `enhance`             | `ImageEnhanceOption` | No       | `ORIGINAL`    | Image enhancement level                                                                                                                                                                                                                                                                                                                               |
| `style`               | `str`                | No       | `None`        | Artistic style (e.g., "fantasy\_art", "cyberpunk")                                                                                                                                                                                                                                                                                                    |
| `traits`              | `List[TraitModel]`   | No       | `None`        | List of traits to apply                                                                                                                                                                                                                                                                                                                               |
| `image`               | `HttpUrl`            | No       | `None`        | Reference image URL for image-to-image generation                                                                                                                                                                                                                                                                                                     |
| `isCharacterPreserve` | `bool`               | No       | `False`       | Preserve character features from reference image                                                                                                                                                                                                                                                                                                      |

**Response Model (`GenerateImageResponseModel`):**

| Field       | Type        | Description                      |
| ----------- | ----------- | -------------------------------- |
| `data.type` | `str`       | Data type (always "Buffer")      |
| `data.data` | `List[int]` | Raw image bytes as integer array |

**Image-to-Image Generation:**

```python
from pydantic import HttpUrl

# Generate image based on a reference image
request = GenerateImageRequestModel(
    prompt="a dragon in space",
    model=NFTImageModel.VELOGEN,
    height=512,
    width=512,
    image=HttpUrl("https://example.com/reference-image.jpg"),
    isCharacterPreserve=True  # Preserve character features from reference
)

response = await client.nft.generate_image(request)
```

**Example:**

```python
async def generate_image_example():
    request = GenerateImageRequestModel(
        prompt="a majestic cyberpunk dragon",
        model=NFTImageModel.VELOGEN,  # Fast model for sync generation
        height=512,
        width=512,
        steps=3,
        enhance=ImageEnhanceOption.ENHANCE_1X,
        style="cyberpunk"
    )
    
    response = await client.nft.generate_image(request)
    
    # Save the image
    image_bytes = bytes(response.data.data)
    with open("generated_image.png", "wb") as f:
        f.write(image_bytes)
    
    print(f"Image generated: {len(image_bytes)} bytes")
```

**Image-to-Image Generation:**

```python
from pydantic import HttpUrl

# Generate image based on a reference image
request = GenerateImageRequestModel(
    prompt="a dragon in space",
    model=NFTImageModel.VELOGEN,
    height=512,
    width=512,
    image=HttpUrl("https://example.com/reference-image.jpg"),
    isCharacterPreserve=True  # Preserve character features
)

response = await client.nft.generate_image(request)
```

**Using Traits:**

```python
from chaingpt.models import TraitModel, TraitValueItemModel

traits = [
    TraitModel(
        trait_type="Background",
        value=[
            TraitValueItemModel(value="night_sky", ratio=70),
            TraitValueItemModel(value="lava_pit", ratio=30)
        ]
    ),
    TraitModel(
        trait_type="Color",
        value=[
            TraitValueItemModel(value="blue", ratio=50),
            TraitValueItemModel(value="red", ratio=50)
        ]
    )
]

request = GenerateImageRequestModel(
    prompt="a dragon",
    model=NFTImageModel.VELOGEN,
    height=512,
    width=512,
    traits=traits
)
```

***

#### generate\_nft\_queue()

Initiates an asynchronous NFT image generation job. Use this for high-quality images or when you don't need immediate results.

**Method Signature:**

```python
async def generate_nft_queue(self, request_data: GenerateNFTQueueRequestModel) -> GenerateNFTQueueResponseModel
```

**Parameters:**

| Parameter      | Type                           | Required | Description               |
| -------------- | ------------------------------ | -------- | ------------------------- |
| `request_data` | `GenerateNFTQueueRequestModel` | Yes      | NFT generation parameters |

**Request Model (`GenerateNFTQueueRequestModel`):**

| Field                 | Type                 | Required | Description                                       |
| --------------------- | -------------------- | -------- | ------------------------------------------------- |
| `walletAddress`       | `str`                | Yes      | Blockchain wallet address for the NFT             |
| `prompt`              | `str`                | Yes      | Text prompt for image generation                  |
| `model`               | `NFTImageModel`      | Yes      | AI model to use                                   |
| `height`              | `int`                | Yes      | Image height in pixels                            |
| `width`               | `int`                | Yes      | Image width in pixels                             |
| `chainId`             | `int`                | Yes      | Blockchain network ID (see get\_chains())         |
| `amount`              | `int`                | Yes      | Number of NFTs to generate in this batch          |
| `steps`               | `int`                | No       | Generation steps                                  |
| `enhance`             | `ImageEnhanceOption` | No       | Enhancement level                                 |
| `style`               | `str`                | No       | Artistic style                                    |
| `traits`              | `List[TraitModel]`   | No       | List of traits                                    |
| `image`               | `HttpUrl`            | No       | Reference image URL for image-to-image generation |
| `isCharacterPreserve` | `bool`               | No       | Preserve character features from reference image  |

**Response Model (`GenerateNFTQueueResponseModel`):**

| Field               | Type  | Description                                  |
| ------------------- | ----- | -------------------------------------------- |
| `statusCode`        | `int` | HTTP status code (201 = successfully queued) |
| `message`           | `str` | Response message                             |
| `data.collectionId` | `str` | Unique ID for tracking this generation job   |

**Example:**

```python
async def generate_nft_queue_example():
    request = GenerateNFTQueueRequestModel(
        walletAddress="0x742d35Cc6635C0532925a3b8D8842A36fF20fd40",
        prompt="A mystical phoenix rising from cosmic ashes",
        model=NFTImageModel.NEBULA_FORGE_XL,  # High-quality model
        height=1024,
        width=1024,
        steps=30,
        enhance=ImageEnhanceOption.ENHANCE_1X,
        chainId=56,  # BSC Mainnet
        amount=1,
        style="cinematic"
    )
    
    response = await client.nft.generate_nft_queue(request)
    
    if response.statusCode == 201:
        print(f"NFT queued successfully!")
        print(f"Collection ID: {response.data.collectionId}")
        return response.data.collectionId
    else:
        print(f"Failed to queue: {response.message}")
        return None
```

***

#### get\_progress()

Checks the status and progress of a queued NFT generation job.

**Method Signature:**

```python
async def get_progress(self, collection_id: str) -> NFTProgressResponseModel
```

**Parameters:**

| Parameter       | Type  | Required | Description                                        |
| --------------- | ----- | -------- | -------------------------------------------------- |
| `collection_id` | `str` | Yes      | Collection ID from `generate_nft_queue()` response |

**Response Model (`NFTProgressResponseModel`):**

| Field            | Type        | Description                                |
| ---------------- | ----------- | ------------------------------------------ |
| `statusCode`     | `int`       | HTTP status code                           |
| `message`        | `str`       | Response message                           |
| `data.generated` | `bool`      | `True` if generation is complete           |
| `data.images`    | `List[str]` | IPFS URLs (only when `generated=True`)     |
| `data.progress`  | `int`       | Progress percentage (only when processing) |

**Example:**

```python
async def track_progress_example(collection_id: str):
    max_attempts = 20
    attempt = 0
    
    while attempt < max_attempts:
        response = await client.nft.get_progress(collection_id)
        
        print(f"Status: {response.data.generated}")
        if response.data.progress:
            print(f"Progress: {response.data.progress}%")
        
        if response.data.generated:
            print("Generation completed!")
            if response.data.images:
                print(f"IPFS URLs: {response.data.images}")
            return True
        
        await asyncio.sleep(15)  # Wait 15 seconds
        attempt += 1
    
    print("Timeout reached")
    return False
```

***

#### mint\_nft\_metadata()

Generates the metadata required for minting NFTs on a blockchain. Call this after NFT generation is complete.

**Method Signature:**

```python
async def mint_nft_metadata(self, request_data: MintNFTRequestModel) -> MintNFTResponseModel
```

**Parameters:**

| Parameter      | Type                  | Required | Description                    |
| -------------- | --------------------- | -------- | ------------------------------ |
| `request_data` | `MintNFTRequestModel` | Yes      | Metadata generation parameters |

**Request Model (`MintNFTRequestModel`):**

| Field          | Type        | Required | Description                                          |
| -------------- | ----------- | -------- | ---------------------------------------------------- |
| `collectionId` | `str`       | Yes      | ID of completed NFT generation job                   |
| `name`         | `str`       | Yes      | Name of the NFT                                      |
| `description`  | `str`       | Yes      | Description of the NFT                               |
| `symbol`       | `str`       | Yes      | Symbol for the NFT collection                        |
| `ids`          | `List[int]` | Yes      | List of NFT IDs to mint (e.g., `[1]` for single NFT) |

**Response Model (`MintNFTResponseModel`):**

| Field               | Type         | Description                         |
| ------------------- | ------------ | ----------------------------------- |
| `statusCode`        | `int`        | HTTP status code                    |
| `message`           | `str`        | Response message                    |
| `data._id`          | `str`        | MongoDB document ID                 |
| `data._id`          | `str`        | MongoDB document ID                 |
| `data.name`         | `str`        | NFT name                            |
| `data.description`  | `str`        | NFT description                     |
| `data.image`        | `str`        | IPFS URL for the NFT image          |
| `data.attributes`   | `List[Dict]` | NFT attributes/traits               |
| `data.collectionId` | `str`        | Collection ID                       |
| `data.transaction`  | `Any`        | Transaction details (if applicable) |
| `data.__v`          | `int`        | MongoDB version field               |
| `data.createdAt`    | `str`        | Creation timestamp                  |
| `data.updatedAt`    | `str`        | Last update timestamp               |
| `data.__v`          | `int`        | MongoDB version field               |
| `data.createdAt`    | `str`        | Creation timestamp                  |
| `data.updatedAt`    | `str`        | Last update timestamp               |

**Example:**

```python
async def mint_metadata_example(collection_id: str):
    request = MintNFTRequestModel(
        collectionId=collection_id,
        name="Cosmic Phoenix #1",
        description="A stunning AI-generated phoenix from the ChainGPT NFT Forge.",
        symbol="CPHX",
        ids=[1]  # Single NFT
    )
    
    response = await client.nft.mint_nft_metadata(request)
    
    if response.statusCode in [200, 201]:
        print("Metadata generated successfully:")
        print(f"  ID: {response.data._id}")
        print(f"  Name: {response.data.name or 'Not provided'}")
        print(f"  Image: {response.data.image or 'Not provided'}")
        print(f"  Attributes: {response.data.attributes or 'None'}")
        print(f"  Collection ID: {response.data.collectionId or 'Not provided'}")
        print(f"  Created At: {response.data.createdAt or 'Not provided'}")
        
        # This metadata can now be used with smart contracts
        return response.data
    else:
        print(f"Failed to generate metadata: {response.message}")
        return None
```

***

#### get\_chains()

Retrieves the list of supported blockchain networks for NFT operations.

**Method Signature:**

```python
async def get_chains(self, test_net: Optional[bool] = None) -> GetChainsResponseModel
```

**Parameters:**

| Parameter  | Type   | Required | Default | Description                                               |
| ---------- | ------ | -------- | ------- | --------------------------------------------------------- |
| `test_net` | `bool` | No       | `None`  | `True` for testnets, `False` for mainnets, `None` for all |

**Response Model (`GetChainsResponseModel`):**

| Field         | Type                   | Description              |
| ------------- | ---------------------- | ------------------------ |
| `statusCode`  | `int`                  | HTTP status code         |
| `message`     | `str`                  | Response message         |
| `data.chains` | `List[ChainInfoModel]` | List of supported chains |

**Chain Info Model (`ChainInfoModel`):**

| Field         | Type  | Description                           |
| ------------- | ----- | ------------------------------------- |
| `chainId`     | `int` | Numerical chain ID                    |
| `chainName`   | `str` | Chain name (e.g., "Ethereum Mainnet") |
| `network`     | `str` | Network type ("mainnet", "testnet")   |
| `networkType` | `str` | Additional network classification     |

**Example:**

```python
async def get_chains_example():
    # Get mainnet chains
    mainnet_response = await client.nft.get_chains(test_net=False)
    print("Mainnet Chains:")
    for chain in mainnet_response.data.chains[:5]:
        print(f"  ID: {chain.chainId}, Name: {chain.chainName}")
    
    # Get testnet chains
    testnet_response = await client.nft.get_chains(test_net=True)
    print("\nTestnet Chains:")
    for chain in testnet_response.data.chains[:5]:
        print(f"  ID: {chain.chainId}, Name: {chain.chainName}")
    
    # Common chain IDs:
    # 1 = Ethereum Mainnet
    # 56 = BSC Mainnet
    # 137 = Polygon Mainnet
    # 97 = BSC Testnet
    # 11155111 = Ethereum Sepolia
```

***

#### get\_abi()

Provides the ABI (Application Binary Interface) of the ChainGPT NFT smart contract for direct blockchain interaction.

**Method Signature:**

```python
async def get_abi(self) -> ContractABIResponseModel
```

**Parameters:** None

**Response Model (`ContractABIResponseModel`):**

| Field        | Type         | Description                  |
| ------------ | ------------ | ---------------------------- |
| `statusCode` | `int`        | HTTP status code             |
| `message`    | `str`        | Response message             |
| `data`       | `List[Dict]` | Contract ABI as JSON objects |

**Example:**

```python
async def get_abi_example():
    response = await client.nft.get_abi()
    
    if response.statusCode == 200:
        abi = response.data
        print(f"Contract ABI contains {len(abi)} functions/events")
        
        # Use with web3.py
        from web3 import Web3
        w3 = Web3(Web3.HTTPProvider("YOUR_RPC_URL"))
        contract = w3.eth.contract(
            address="CONTRACT_ADDRESS",
            abi=abi
        )
        
        return abi
    else:
        print(f"Failed to get ABI: {response.message}")
        return None
```

***

### Data Models & Types

#### TraitModel

Defines NFT traits/attributes for generation:

```python
class TraitModel(BaseModel):
    trait_type: str          # Name of the trait (e.g., "Background", "Color")
    value: List[TraitValueItemModel]  # Possible values with ratios

class TraitValueItemModel(BaseModel):
    value: str               # Specific trait value (e.g., "night_sky")
    ratio: int              # Rarity/probability (higher = more common)
```

#### Error Models

All methods can raise the following exceptions:

```python
from chaingpt.exceptions import (
    ChainGPTError,          # Base exception
    APIError,               # API-specific errors
    AuthenticationError,    # Invalid API key (401)
    ValidationError,        # Bad request (400)
    InsufficientCreditsError, # No credits (402/403)
    RateLimitError,         # Too many requests (429)
    NotFoundError,          # Endpoint not found (404)
    ServerError,            # Server errors (5xx)
    TimeoutError           # Request timeout
)
```

***

### Enums Reference

#### NFTImageModel

Available AI models for image generation:

| Model             | Value               | Description       | Best For                 |
| ----------------- | ------------------- | ----------------- | ------------------------ |
| `VELOGEN`         | `"velogen"`         | Fast generation   | Quick previews, testing  |
| `NEBULA_FORGE_XL` | `"nebula_forge_xl"` | High quality      | Final NFTs, detailed art |
| `VISIONARY_FORGE` | `"VisionaryForge"`  | Balanced          | General purpose          |
| `DALE3`           | `"Dale3"`           | Alternative model | Experimental             |

#### ImageEnhanceOption

Image enhancement levels:

| Option       | Value        | Description    |
| ------------ | ------------ | -------------- |
| `ORIGINAL`   | `"original"` | No enhancement |
| `ENHANCE_1X` | `"1x"`       | 1x enhancement |
| `ENHANCE_2X` | `"2x"`       | 2x enhancement |

***

### Error Handling

#### Basic Error Handling

```python
from chaingpt.exceptions import ChainGPTError, APIError

async def safe_nft_generation():
    try:
        request = GenerateImageRequestModel(
            prompt="a dragon",
            model=NFTImageModel.VELOGEN,
            height=512,
            width=512
        )
        response = await client.nft.generate_image(request)
        return response
        
    except AuthenticationError:
        print("Invalid API key!")
    except ValidationError as e:
        print(f"Invalid request: {e.message}")
        if e.field:
            print(f"Problem with field: {e.field}")
    except InsufficientCreditsError:
        print("Not enough credits in your account")
    except RateLimitError as e:
        print(f"Rate limited. Retry after: {e.retry_after} seconds")
    except APIError as e:
        print(f"API error {e.status_code}: {e.message}")
    except ChainGPTError as e:
        print(f"General error: {e.message}")
```

#### Specific Error Scenarios

```python
# Handle generation failures
async def robust_generation(collection_id: str):
    try:
        while True:
            progress = await client.nft.get_progress(collection_id)
            
            if progress.data.generated:
                return progress.data.images
            elif progress.statusCode >= 400:
                raise ChainGPTError("Generation failed")
            
            await asyncio.sleep(10)
            
    except ChainGPTError as e:
        print(f"Generation error: {e}")
        return None
```

***

### Complete Example

Here's a comprehensive example showing the full NFT creation workflow:

```python
import asyncio
import os
from chaingpt.client import ChainGPTClient
from chaingpt.models import *
from chaingpt.exceptions import ChainGPTError

async def complete_nft_workflow():
    """Complete NFT generation workflow from prompt to metadata."""
    
    # Initialize client
    client = ChainGPTClient(api_key=os.getenv("CHAINGPT_API_KEY"))
    
    try:
        # Step 1: Enhance the prompt
        print("1. Enhancing prompt...")
        enhance_request = EnhancePromptRequestModel(
            prompt="a mystical dragon guardian"
        )
        enhanced = await client.nft.enhance_prompt(enhance_request)
        enhanced_prompt = enhanced.data.enhancedPrompt
        print(f"Enhanced: {enhanced_prompt}")
        
        # Step 2: Generate a quick preview
        print("\n2. Generating preview...")
        preview_request = GenerateImageRequestModel(
            prompt=enhanced_prompt,
            model=NFTImageModel.VELOGEN,
            height=512,
            width=512,
            enhance=ImageEnhanceOption.ORIGINAL
        )
        preview = await client.nft.generate_image(preview_request)
        
        # Save preview
        with open("preview.jpg", "wb") as f:
            f.write(bytes(preview.data.data))
        print("Preview saved as preview.jpg")
        
        # Step 3: Queue high-quality NFT generation
        print("\n3. Queueing NFT generation...")
        nft_request = GenerateNFTQueueRequestModel(
            walletAddress="0x742d35Cc6635C0532925a3b8D8842A36fF20fd40",
            prompt=enhanced_prompt,
            model=NFTImageModel.NEBULA_FORGE_XL,
            height=1024,
            width=1024,
            steps=30,
            enhance=ImageEnhanceOption.ENHANCE_1X,
            chainId=56,  # BSC Mainnet
            amount=1,
            style="fantasy-art",
            traits=[
                TraitModel(
                    trait_type="Element",
                    value=[
                        TraitValueItemModel(value="fire", ratio=60),
                        TraitValueItemModel(value="ice", ratio=40)
                    ]
                )
            ]
        )
        
        queue_response = await client.nft.generate_nft_queue(nft_request)
        collection_id = queue_response.data.collectionId
        print(f"Queued with ID: {collection_id}")
        
        # Step 4: Track progress
        print("\n4. Tracking progress...")
        max_attempts = 20
        for attempt in range(max_attempts):
            progress = await client.nft.get_progress(collection_id)
            print(f"Attempt {attempt + 1}: Generated: {progress.data.generated} - Progress: {progress.data.progress}%")
            
            if progress.data.generated:
                print(f"Completed! IPFS URLs: {progress.data.images}")
                break
            
            await asyncio.sleep(15)
        else:
            raise ChainGPTError("Generation timeout")
        
        # Step 5: Generate metadata
        print("\n5. Generating metadata...")
        metadata_request = MintNFTRequestModel(
            collectionId=collection_id,
            name="Mystical Dragon Guardian #1",
            description="An AI-generated mystical dragon guardian, protector of ancient realms.",
            symbol="MDG",
            ids=[1]
        )
        
        metadata = await client.nft.mint_nft_metadata(metadata_request)
        print("Metadata generated:")
        print(f"  ID: {metadata.data._id}")
        print(f"  Name: {metadata.data.name or 'Not provided'}")
        print(f"  Image: {metadata.data.image or 'Not provided'}")
        print(f"  Attributes: {metadata.data.attributes or 'None'}")
        
        # Step 6: Get chain info for minting
        print("\n6. Getting chain information...")
        chains = await client.nft.get_chains(test_net=False)
        bsc_mainnet = next((c for c in chains.data.chains if c.chainId == 56), None)
        if bsc_mainnet:
            print(f"Target chain: {bsc_mainnet.chainName} (ID: {bsc_mainnet.chainId})")
        
        # Step 7: Get contract ABI
        print("\n7. Getting contract ABI...")
        abi_response = await client.nft.get_abi()
        print(f"Contract ABI received (first few elements): {abi_response.data[:2]}")
        
        print("\n✅ NFT workflow completed successfully!")
        return metadata.data
        
    except ChainGPTError as e:
        print(f"❌ Error: {e}")
        return None
        
    finally:
        await client.close()

# Run the complete workflow
if __name__ == "__main__":
    result = asyncio.run(complete_nft_workflow())
```

***

### Best Practices

#### 1. Resource Management

Always close the client when done:

```python
async def proper_usage():
    client = ChainGPTClient(api_key="YOUR_API_KEY")
    try:
        # Your NFT operations here
        pass
    finally:
        await client.close()

# Or use async context manager if available
async with ChainGPTClient(api_key="YOUR_API_KEY") as client:
    # Operations here
    pass
```

#### 2. Error Handling

Handle specific errors appropriately:

```python
async def robust_operation():
    try:
        # Your operation
        pass
    except AuthenticationError:
        # Handle auth issues - check API key
        pass
    except InsufficientCreditsError:
        # Handle billing issues
        pass
    except RateLimitError as e:
        # Handle rate limiting - wait and retry
        await asyncio.sleep(e.retry_after or 60)
    except ValidationError as e:
        # Handle validation errors - fix request
        print(f"Fix field: {e.field}")
```

#### 3. Progress Tracking

Use reasonable polling intervals:

```python
async def track_with_backoff(collection_id: str):
    wait_time = 10  # Start with 10 seconds
    max_wait = 60   # Max 60 seconds between polls
    
    while True:
        progress = await client.nft.get_progress(collection_id)
        
        if progress.data.generated:
            return progress.data.images
        
        await asyncio.sleep(wait_time)
        wait_time = min(wait_time * 1.2, max_wait)  # Exponential backoff
```

#### 4. Model Selection

Choose the right model for your use case:

```python
# For quick previews and testing
preview_model = NFTImageModel.VELOGEN

# For final high-quality NFTs
production_model = NFTImageModel.NEBULA_FORGE_XL

# Adjust steps based on model and quality needs
quick_steps = 10      # For previews
quality_steps = 30    # For final NFTs
```

#### 5. Prompt Engineering

Create effective prompts:

```python
# Good prompt structure
prompt = "a majestic dragon, fantasy art, highly detailed, vibrant colors, mystical atmosphere"

# Use enhancement for better results
enhanced = await client.nft.enhance_prompt(
    EnhancePromptRequestModel(prompt=prompt)
)
final_prompt = enhanced.data.enhancedPrompt
```

***

### New Features

#### Image-to-Image Generation

The NFT service now supports image-to-image generation, allowing you to create variations based on reference images:

```python
from pydantic import HttpUrl

# Generate image based on a reference image
request = GenerateImageRequestModel(
    prompt="a dragon in space",
    model=NFTImageModel.VELOGEN,
    height=512,
    width=512,
    image=HttpUrl("https://example.com/reference-image.jpg"),
    isCharacterPreserve=True  # Preserve character features from reference
)

response = await client.nft.generate_image(request)
```

#### Character Preservation

When using image-to-image generation, you can preserve character features from the reference image:

```python
# Preserve character features
request = GenerateImageRequestModel(
    prompt="a dragon in a cyberpunk city",
    model=NFTImageModel.NEBULA_FORGE_XL,
    height=1024,
    width=1024,
    image=HttpUrl("https://example.com/dragon-reference.jpg"),
    isCharacterPreserve=True  # Maintains dragon's appearance
)
```

#### Enhanced Traits System

The traits system has been enhanced with better support for NFT collections:

```python
traits = [
    TraitModel(
        trait_type="Background",
        value=[
            TraitValueItemModel(value="night_sky", ratio=70),
            TraitValueItemModel(value="lava_pit", ratio=30)
        ]
    ),
    TraitModel(
        trait_type="Accessory",
        value=[
            TraitValueItemModel(value="crown", ratio=20),
            TraitValueItemModel(value="sword", ratio=40),
            TraitValueItemModel(value="none", ratio=40)
        ]
    )
]
```

#### Updated Chain Support

The chain information now includes more detailed network information:

```python
chains = await client.nft.get_chains(test_net=False)
for chain in chains.data.chains:
    print(f"Chain: {chain.chainName}")
    print(f"  ID: {chain.chainId}")
    print(f"  Network: {chain.network}")
    print(f"  Type: {chain.networkType}")
```

#### Improved Response Structures

All API responses now follow a consistent structure with proper error handling:

```python
# All responses include statusCode, message, and data
response = await client.nft.enhance_prompt(request)
if response.statusCode == 200:
    enhanced_prompt = response.data.enhancedPrompt
else:
    print(f"Error: {response.message}")
```

This ensures better error handling and consistent data access patterns across all NFT service methods.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chaingpt.org/dev-docs-b2b-saas-api-and-sdk/ai-nft-generator-api-and-sdk/python.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.