Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.together.ai/llms.txt

Use this file to discover all available pages before exploring further.

Using a coding agent? Install the together-images skill to let your agent write correct image generation code automatically. Learn more.

​
Generating an image

To query an image model, use the .images method and specify the image model you want to use. 
client = Together()

# Generate an image from a text prompt
response = client.images.generate(
    prompt="A serene mountain landscape at sunset with a lake reflection",
    model="black-forest-labs/FLUX.1-schnell",
    steps=4,
)

print(f"Image URL: {response.data[0].url}")
Example response structure and output: 
{
  "id": "oFuwv7Y-2kFHot-99170ebf9e84e0ce-SJC",
  "model": "black-forest-labs/FLUX.1-schnell",
  "data": [
    {
      "index": 0,
      "url": "https://api.together.ai/v1/images/..."
    }
  ]
}
Reference image: image-overview1.png

​
Provide reference image

Some image models support editing or transforming an existing image. The parameter you use depends on the model:
ParameterTypeModelsDescription
image_urlstringFLUX.1 Kontext (pro/max), FLUX.2 (pro/flex)A single image URL to edit or transform
reference_imagesstring[]FLUX.2 (pro/dev/flex), Gemini 3 Pro Image, Flash Image 2.5An array of image URLs to guide generation
reference_images is recommended for FLUX.2 and Google models as it supports multiple input images. FLUX.2 [pro] and [flex] also accept image_url for single-image edits, but FLUX.2 [dev], Gemini 3 Pro Image, and Flash Image 2.5 only support reference_images.

​
Using image_url (Kontext models)

from together import Together

client = Together()

response = client.images.generate(
    model="black-forest-labs/FLUX.1-kontext-pro",
    width=1024,
    height=768,
    prompt="Transform this into a watercolor painting",
    image_url="https://cdn.pixabay.com/photo/2020/05/20/08/27/cat-5195431_1280.jpg",
)
Example output: Reference image: reference_image.png

​
Using reference_images (FLUX.2 & Google models)

from together import Together

client = Together()

response = client.images.generate(
    model="black-forest-labs/FLUX.2-pro",
    width=1024,
    height=768,
    prompt="Replace the color of the car to blue",
    reference_images=[
        "https://images.pexels.com/photos/3729464/pexels-photo-3729464.jpeg"
    ],
)
For more details on multi-image editing, image indexing, and color control with FLUX.2, see the FLUX.2 Quickstart.

​
Supported Models

See our models page for supported image models.

​
Parameters

ParameterTypeDescriptionDefault
promptstringText description of the image to generateRequired
modelstringModel identifierRequired
widthintegerImage width in pixels1024
heightintegerImage height in pixels1024
nintegerNumber of images to generate (1-4)1
stepsintegerDiffusion steps (higher = better quality, slower)1-50
seedintegerRandom seed for reproducibilityany
negative_promptstringWhat to avoid in generation-
image_urlstringURL of a reference image to edit. Used by Kontext models.-
reference_imagesarrayArray of image URLs for image-to-image editing. Used by FLUX.2 and Google models.-
frame_imagesarrayRequired for Kling model. Array of images to guide video generation, like keyframes.-
  • prompt is required for all models except Kling
  • width and height will rely on defaults unless otherwise specified - options for dimensions differ by model
  • Flux Schnell and Kontext [Pro/Max/Dev] models use the aspect_ratio parameter to set the output image size whereas Flux.1 Pro, Flux 1.1 Pro, and Flux.1 Dev use width and height parameters.

​
Generating Multiple Variations

Generate multiple variations of the same prompt to choose from: 
response = client.images.generate(
    prompt="A cute robot assistant helping in a modern office",
    model="black-forest-labs/FLUX.1-schnell",
    n=4,
    steps=4,
)

print(f"Generated {len(response.data)} variations")
for i, image in enumerate(response.data):
    print(f"Variation {i+1}: {image.url}")
Example output: Multiple generated image variations

​
Custom Dimensions & Aspect Ratios

Different aspect ratios for different use cases: 
# Square - Social media posts, profile pictures
response_square = client.images.generate(
    prompt="A peaceful zen garden with a stone path",
    model="black-forest-labs/FLUX.1-schnell",
    width=1024,
    height=1024,
    steps=4,
)

# Landscape - Banners, desktop wallpapers
response_landscape = client.images.generate(
    prompt="A peaceful zen garden with a stone path",
    model="black-forest-labs/FLUX.1-schnell",
    width=1344,
    height=768,
    steps=4,
)

# Portrait - Mobile wallpapers, posters
response_portrait = client.images.generate(
    prompt="A peaceful zen garden with a stone path",
    model="black-forest-labs/FLUX.1-schnell",
    width=768,
    height=1344,
    steps=4,
)
Reference image: dims.png

​
Quality Control with Steps

Compare different step counts for quality vs. speed: 
import time

prompt = "A majestic mountain landscape"
step_counts = [1, 6, 12]

for steps in step_counts:
    start = time.time()
    response = client.images.generate(
        prompt=prompt,
        model="black-forest-labs/FLUX.1-schnell",
        steps=steps,
        seed=42,  # Same seed for fair comparison
    )
    elapsed = time.time() - start
    print(f"Steps: {steps} - Generated in {elapsed:.2f}s")
Reference image: steps.png

​
Base64 Images

If you prefer the image data to be embedded directly in the response, set response_format to “base64”. 
from together import Together

client = Together()

response = client.images.generate(
    model="black-forest-labs/FLUX.1-schnell",
    prompt="a cat in outer space",
    response_format="base64",
)

print(response.data[0].b64_json)
When you do, the model response includes a new b64_json field that contains the image encoded as a base64 string. 
{
  "id": "oNM6X9q-2kFHot-9aa9c4c93aa269a2-PDX",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQA",
      "index": 0,
      "type": null,
      "timings": {
        "inference": 0.7992482790723443
      }
    }
  ],
  "model": "black-forest-labs/FLUX.1-schnell",
  "object": "list"
}

​
Safety Checker

We have a built in safety checker that detects NSFW words but you can disable it by passing in disable_safety_checker=True. This works for every model except Flux Schnell Free and Flux Pro. If the safety checker is triggered and not disabled, it will return a 422 Unprocessable Entity. 
from together import Together

client = Together()

response = client.images.generate(
    prompt="a flying cat",
    model="black-forest-labs/FLUX.1-schnell",
    steps=4,
    disable_safety_checker=True,
)

print(response.data[0].url)

​
Troubleshooting

Image doesn’t match prompt well
  • Make prompt more descriptive and specific
  • Add style references (e.g., “National Geographic style”)
  • Use negative prompts to exclude unwanted elements
  • Try increasing steps to 30-40
Poor image quality
  • Increase steps to 30-40 for production
  • Add quality modifiers: “highly detailed”, “8k”, “professional”
  • Use negative prompt: “blurry, low quality, distorted, pixelated”
  • Try a higher-tier model
Inconsistent results
  • Use seed parameter for reproducibility
  • Keep the same seed when testing variations
  • Generate multiple variations with n parameter
Wrong dimensions or aspect ratio
  • Specify width and height explicitly
  • Common ratios:
    • Square: 1024x1024
    • Landscape: 1344x768
    • Portrait: 768x1344
  • Ensure dimensions are multiples of 8