Image Generation

​

Prerequisites

1. API Key: Sign up on the Nscale platform to get your API key.

2. Model Selection: Choose an image generation model from Nscale’s model library.

   • Example: FLUX.1 [schnell] black-forest-labs/FLUX.1-schnell

​

Step 1: Set up your environment

Before making requests, ensure you have the necessary tools installed for your language of choice:

For Python: Install openai library

pip install openai

For Typescript: Install openai library

npm install openai

For cURL: Ensure cURL is installed on your system (it’s usually pre-installed on most Unix-based systems).

​

Step 2: Sending an image generation request

Let’s walk through an example where we generate an image based on a text prompt.

Request structure

Each request to the Nscale Image Generation API endpoint should include the following:

1. Headers:

   • "Authorization": "Bearer <API-KEY>"

   • "Content-Type": "application/json"

2. Payload:

   • "model": "<model id e.g., black-forest-labs/FLUX.1-schnell>"
   • "prompt": "<text description of the desired image>"
   • "size": "<image size, defaults to 512x512>"
   • "n": "<number of images to generate, defaults to 1>"

Example use case: Generate a landscape at sunset

import os
import openai

nscale_api_key = os.getenv("NSCALE_API_KEY")
nscale_base_url = "https://inference.api.nscale.com/v1"

client = openai.OpenAI(
    api_key=nscale_api_key,
    base_url=nscale_base_url
)

response = client.images.generate(
    model="black-forest-labs/FLUX.1-schnell",
    prompt="A serene mountain landscape at sunset with a lake reflecting the orange sky",
    size="1024x1024",  # Optional
    n=1  # Optional
)

print(response.data[0].b64_json)

​

Step 3: Understanding the Response

The response from the image generation API contains:

• A base64-encoded image in the b64_json field
• A timestamp of when the image was created
• The response is returned as a single object, with an array of generated images in the data field

Here’s the output from the example request:

​

Step 4: Using the CLI for Image Generation

You can also use the Nscale CLI to generate images. This is a convenient way to test models or build command-line applications.

​

Prerequisites

• Ensure you have the Nscale CLI installed

​

Examples

Here are some examples of using the CLI for image generation:

# Generate an image with default settings
nscale images generate "A sunset over mountains" -a $NSCALE_API_KEY -m black-forest-labs/FLUX.1-schnell

# Generate an image with custom size
nscale images generate "A futuristic city" -z 1024x1024 -a $NSCALE_API_KEY -m black-forest-labs/FLUX.1-schnell

# Generate and automatically open the image
nscale images generate "A cat playing piano" -x -a $NSCALE_API_KEY -m black-forest-labs/FLUX.1-schnell

# Generate with ASCII preview
nscale images generate "An abstract painting" -p -a $NSCALE_API_KEY -m black-forest-labs/FLUX.1-schnell

# Generate with custom output location
nscale images generate "A forest landscape" -o ./my-image.png -a $NSCALE_API_KEY -m black-forest-labs/FLUX.1-schnell

# Use API key from environment variable
export NSCALE_API_KEY=your_api_key
nscale images generate "A sunset over mountains" -m black-forest-labs/FLUX.1-schnell

For more details on CLI usage, refer to the CLI documentation.

​

Step 5: Monitoring and scaling

Nscale handles scaling automatically based on traffic patterns—no manual intervention needed! Use the Nscale Console to monitor:

• API usage by model

• Spend breakdowns

For custom models or high-throughput applications on dedicated endpoints, contact Nscale Support.

​

Troubleshooting

Common status codes and their meanings:

​

Success Response Format (200)

{
  "created": 1677652288,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

​

Error Response Format

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "You have insufficient credit to run this request",
    "param": null,
    "error_type": "INSUFFICIENT_CREDIT"
  }
}

For the extensive list of error codes and handling, see the error code page

​

Available Models

For a complete list of available image generation models and their pricing, please refer to our models page.