Image Endpoints

POST /api/v1/studio/image/generate

Generate images from a text prompt using various AI models.

Request Body

promptstringrequired

Image description (3–2000 characters).

modelstring

Model ID. One of: nano-banana (default), nano-banana-pro, seedream, gpt-image, gpt-image-mini, gpt-image-2, gemini-imagen, imagen-ultra, grok-imagine.

numImagesnumber

Number of images to generate (1–10, varies by model).

aspectRatiostring

Aspect ratio (e.g. "16:9", "1:1"). Varies by model.

outputFormatstring

Output format: jpeg, png, or webp.

resolutionstring

Resolution: 1K, 2K, or 4K (nano-banana-pro only).

widthnumber

Width in pixels (1024–4096, seedream only).

heightnumber

Height in pixels (1024–4096, seedream only).

seednumber

Seed for reproducibility (0–2147483647).

negativePromptstring

Negative prompt (imagen-ultra only).

qualitystring

Quality: auto, low, medium, high (gpt-image, gpt-image-2).

backgroundstring

Background: auto, transparent, opaque (gpt-image only).

imageSizestring | object

For gpt-image-2: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3 (default), landscape_16_9, or a custom { width, height } object (multiples of 16).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/image/generate \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene sunset over mountains",
    "model": "nano-banana",
    "numImages": 1,
    "aspectRatio": "16:9"
  }'

Response

JSON

{
  "success": true,
  "data": {
    "model": "nano-banana",
    "images": [
      {
        "url": "https://storage.googleapis.com/...",
        "contentType": "image/jpeg",
        "width": 1024,
        "height": 576
      }
    ],
    "metadata": {
      "outputImages": 1,
      "prompt": "A serene sunset over mountains",
      "aspectRatio": "16:9"
    }
  },
  "credits": { "used": 1, "cost": 5.0, "remaining": 9995.0 }
}

Billing & Credit Reservation

Credits are reserved up-front before the job starts and charged only on success. If the generation fails (provider error, invalid input, storage failure) the reservation is released and your balance is untouched. When a model is queued asynchronously (async: true or returns HTTP 202), the reservation is settled by the fal webhook — success charges, failure releases. Insufficient balance returns 402 INSUFFICIENT_CREDITS; hitting the 6-hour usage window returns 429 WINDOW_EXHAUSTED with a resetAt timestamp. See Credit Reservation for details.

POST /api/v1/studio/image/edit

Edit existing images using text instructions and reference image URLs.

Request Body

promptstringrequired

Edit instructions (3–2000 characters).

imageUrlsstring[]required

Array of image URLs to edit (1–10).

modelstring

Model: nano-banana (default), seedream, or gpt-image-2.

numImagesnumber

Number of output images.

outputFormatstring

Output format: jpeg, png, or webp.

seednumber

Seed for reproducibility.

Example

curl

curl -X POST https://terramind.com/api/v1/studio/image/edit \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Make the sky more dramatic with storm clouds",
    "imageUrls": ["https://example.com/photo.jpg"],
    "model": "nano-banana"
  }'

POST /api/v1/studio/image/upscale

Upscale an image by 2x, 4x, or 6x. Accepts application/json with an imageUrl. Returns a JSON payload with the hosted upscaled image URL.

Body

imageUrlstringrequired

The URL of the image to upscale.

scaleFactornumber

Scale factor: 2 (default), 4, or 6.

servicestring

Service: fal (default) or clipdrop.

modelstring

Model (fal only): Standard V2, High Fidelity V2, CGI, Low Resolution V2.

faceEnhancementboolean

Enable face enhancement (fal only, default: true).

persistToStorageboolean

Store the result and return a hosted URL (default: false).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/image/upscale \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/photo.png",
    "scaleFactor": 4,
    "persistToStorage": true
  }'

POST /api/v1/studio/image/remove-background

Remove the background from an image. Accepts application/json with an imageUrl. Returns a JSON payload with the hosted result URL.

Body

imageUrlstringrequired

The URL of the image.

modelstring

Model: General Use (Light) (default), General Use (Heavy), or Portrait.

operatingResolutionstring

Resolution: 1024x1024 (default), 2048x2048, or 2304x2304.

refineForegroundboolean

Refine foreground edges (default: true).

persistToStorageboolean

Store the result and return a hosted URL (default: false).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/image/remove-background \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/photo.png",
    "model": "Portrait",
    "persistToStorage": true
  }'

POST /api/v1/studio/image/batch

Batch process multiple images with a single operation. Takes a JSON body with an array of image URLs. For local files, upload each first via POST /api/v1/storage/upload-url and pass the returned fileUrls.

Request Body

operationstringrequired

Operation: remove-background or upscale.

imageUrlsstring[]required

Array of image URLs to process (1–10).

scaleFactornumber

Scale factor for upscale operation (default: 2).

servicestring

Service for upscale (fal default, or clipdrop).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/image/batch \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "upscale",
    "imageUrls": [
      "https://example.com/a.png",
      "https://example.com/b.png"
    ],
    "scaleFactor": 2
  }'

Response

JSON

{
  "success": true,
  "data": {
    "total": 2,
    "successful": 2,
    "failed": 0,
    "results": [
      { "success": true, "index": 0, "data": "https://fal.ai/up-0.png" },
      { "success": true, "index": 1, "data": "https://fal.ai/up-1.png" }
    ]
  },
  "credits": { "used": 1, "cost": 10.0, "remaining": 9990.0 }
}