Image Generation

This guide will walk you through integrating image generation models into your application using Nscale’s API. With our serverless architecture, you can focus on building your application without worrying about infrastructure management.

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

Python

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:

Status	Description	Response Format
200	Success	application/json response with image data
401	Invalid API key or unauthorized	Error object
404	Model not found or unavailable	Error object
429	Insufficient credit	Error object
500	Internal server error	Error object
503	Service temporarily unavailable	Error object

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.

Contact Support

Need assistance? Get help from our support team