​
Prerequisites

  1. Service Token: Sign up on the Nscale platform to create your service token.
  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 <SERVICE-TOKEN>"
    • "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_service_token = os.getenv("NSCALE_SERVICE_TOKEN")
nscale_base_url = "https://inference.api.nscale.com/v1"

client = openai.OpenAI(
    api_key=nscale_service_token,
    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: Example request generated image

​
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

​
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_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell

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

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

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

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

# Use service token from environment variable
export NSCALE_SERVICE_TOKEN=your_service_token
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:
StatusDescriptionResponse Format
200Successapplication/json response with image data
401Invalid service token or unauthorizedError object
404Model not found or unavailableError object
429Insufficient creditError object
500Internal server errorError object
503Service temporarily unavailableError 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