Segmind SceneCraft v0.1 Serverless API

SceneCraft transforms plain or existing product images into visually rich, photorealistic scenes. Whether starting from a white background or enhancing existing settings, it works seamlessly across furniture, home decor, and consumer goods.

~33.64s
POST /v2/segmind-scenecraft-v01 · submit + poll
 1# pip install "segmind>=1.1.0"
 2# export SEGMIND_API_KEY="YOUR_API_KEY"
 3import segmind
 4
 5# Async (v2): submit to the queue and block until COMPLETED.
 6# run() returns the final result dict (600s deadline, 1.0s poll by default).
 7result = segmind.run(
 8    "segmind-scenecraft-v01",
 9    image="https://segmind-resources.s3.amazonaws.com/input/ea6c55f7-f97d-49e4-964f-09cfd27082f5-sofa_WSFABLZPN3FRAB_2.png",
10    prompt="Create a close-up and mid-range product shot of a modern living room sofa with a matte fabric texture and detailed stitching. The scene is set in a warm, cozy living space with soft ambient lighting coming from a side window filtered through sheer linen curtains. Accentuate the sofa’s contours with gentle, natural shadows and subtle reflections on nearby decor elements like a coffee table and floor lamp. Use a color palette dominated by earthy tones — warm beige, soft greys, and muted olive — to create a harmonious and inviting atmosphere. Include a minimalistic rug, wooden flooring, and a few aesthetic accessories like throw pillows and a blanket to enhance lifestyle appeal. Emphasize depth of field for a realistic photographic finish.",
11    negative_prompt="blur, CGI, animated",
12    seed=-1,
13    steps=40,
14    guidance_scale=7,
15    x_value=50,
16    y_value=50,
17    scale=0.65,
18    megapixel="1.5",
19    aspect_ratio="16:9 (Panorama)",
20    dropshadow=True,
21    upscale=False,
22    image_format="jpeg",
23    image_quality=90,
24)
25print(result["status"])                      # COMPLETED
26print(result.get("output"))                  # model output (e.g. media URL)
27print(result["metrics"]["inference_time"])   # server compute seconds
28
29# --- Or submit + poll manually (track request_id, control the cadence) ---
30from segmind import SegmindClient, InferenceFailed, InferenceTimeout
31
32client = SegmindClient()                      # reads SEGMIND_API_KEY
33payload = {
34    "image": "https://segmind-resources.s3.amazonaws.com/input/ea6c55f7-f97d-49e4-964f-09cfd27082f5-sofa_WSFABLZPN3FRAB_2.png",
35    "prompt": "Create a close-up and mid-range product shot of a modern living room sofa with a matte fabric texture and detailed stitching. The scene is set in a warm, cozy living space with soft ambient lighting coming from a side window filtered through sheer linen curtains. Accentuate the sofa’s contours with gentle, natural shadows and subtle reflections on nearby decor elements like a coffee table and floor lamp. Use a color palette dominated by earthy tones — warm beige, soft greys, and muted olive — to create a harmonious and inviting atmosphere. Include a minimalistic rug, wooden flooring, and a few aesthetic accessories like throw pillows and a blanket to enhance lifestyle appeal. Emphasize depth of field for a realistic photographic finish.",
36    "negative_prompt": "blur, CGI, animated",
37    "seed": -1,
38    "steps": 40,
39    "guidance_scale": 7,
40    "x_value": 50,
41    "y_value": 50,
42    "scale": 0.65,
43    "megapixel": "1.5",
44    "aspect_ratio": "16:9 (Panorama)",
45    "dropshadow": True,
46    "upscale": False,
47    "image_format": "jpeg",
48    "image_quality": 90,
49}
50job = client.submit_async("segmind-scenecraft-v01", **payload)
51print(job.request_id)                         # available immediately
52try:
53    result = job.wait(timeout=600, interval=1.0)
54except InferenceTimeout as e:
55    print("still running:", e.request_id)
56except InferenceFailed as e:
57    print("failed:", e.detail)

API Endpoint

POSThttps://api.segmind.com/v1/segmind-scenecraft-v01

Parameters

imagerequired
string (uri)

Specifies the URL for the product image. Use high-quality images for best results.

Default: "https://segmind-resources.s3.amazonaws.com/input/ea6c55f7-f97d-49e4-964f-09cfd27082f5-sofa_WSFABLZPN3FRAB_2.png"
promptrequired
string

Main directive for generating the image. Use specific requests for detailed images.

Default: "Create a close-up and mid-range product shot of a modern living room sofa with a matte fabric texture and detailed stitching. The scene is set in a warm, cozy living space with soft ambient lighting coming from a side window filtered through sheer linen curtains. Accentuate the sofa’s contours with gentle, natural shadows and subtle reflections on nearby decor elements like a coffee table and floor lamp. Use a color palette dominated by earthy tones — warm beige, soft greys, and muted olive — to create a harmonious and inviting atmosphere. Include a minimalistic rug, wooden flooring, and a few aesthetic accessories like throw pillows and a blanket to enhance lifestyle appeal. Emphasize depth of field for a realistic photographic finish."
aspect_ratiooptional
string

Determines the image's width-to-height ratio. Choose based on the desired output shape.

Default: "16:9 (Panorama)"
Allowed values (23 total):
"1:1 (Perfect Square)""2:3 (Classic Portrait)""3:4 (Golden Ratio)""3:5 (Elegant Vertical)""4:5 (Artistic Frame)""5:7 (Balanced Portrait)""5:8 (Tall Portrait)""7:9 (Modern Portrait)""9:16 (Slim Vertical)""9:19 (Tall Slim)"+13 more
dropshadowoptional
boolean

Adds a shadow for depth perception. Ideal for enhancing image realism.

Default: true
guidance_scaleoptional
number

Controls how closely the image matches the prompt. Higher values increase prompt adherence.

Default: 7Range: 1 - 20
image_formatoptional
string

Selects the output file format. Use PNG for lossless quality.

Default: "jpeg"
Allowed values :
"png""jpeg""webp"
image_qualityoptional
integer

Determines the compression level; higher values retain more detail.

Default: 90Range: 10 - 100
megapixeloptional
number

Sets the image resolution in megapixels. Use higher settings for crisp images.

Default: 1.5
Allowed values :
0.10.5
1.01
1.5
2.02
2.12.22.32.42.5
negative_promptoptional
string

Specifies elements to avoid in the image. Useful for excluding undesired features.

Default: "blur, CGI, animated"
scaleoptional
number

Adjusts the size of the generated image. Fine-tune the scale for detail or abstraction.

Default: 0.65Range: 0 - 1
seedoptional
integer

Seed number for reproducibility in image generation. Use -1 for random variance.

Default: -1
stepsoptional
integer

Defines the granularity of image generation. More steps result in finer detail.

Default: 40Range: 1 - 50
upscaleoptional
boolean

Increases the image resolution for sharper outputs. Recommended for print-quality images.

Default: false
x_valueoptional
number

X-axis coordinate for image positioning. Adjust for specific scene framing.

Default: 50Range: 1 - 100
y_valueoptional
number

Y-axis coordinate for image positioning. Use to modify vertical framing.

Default: 50Range: 1 - 100

Response Type

Returns: Image

Asynchronous requests (v2)

Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.

  1. 1
    POST /v2/segmind-scenecraft-v01

    Submitreturns request_id, status_url, response_url

  2. 2
    GET /v2/requests/{id}/status

    Polluntil COMPLETED or FAILED

  3. 3
    GET /v2/requests/{id}

    Resultfinal response body

Status states

QUEUEDAccepted, waiting for a worker
PROCESSINGRunning on a worker
COMPLETEDDone — result body is ready
FAILEDErrored (incl. content/RAI blocks)
  • A FAILED request is served as HTTP 422 — the body still carries the error detail.
  • An unknown or expired request_id returns HTTP 404.
  • Results are retained for 1 hour, then expire.
  • Content / RAI blocks surface as FAILED, not a separate state.
  • Track completion by polling the status endpoint.

Common Error Codes

The API returns standard HTTP status codes. Detailed error messages are provided in the response body.

400

Bad Request

Invalid parameters or request format

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Model or endpoint not found

406

Insufficient Credits

Not enough credits to process request

429

Rate Limited

Too many requests

500

Server Error

Internal server error

502

Bad Gateway

Service temporarily unavailable

504

Timeout

Request timed out