API Documentation

Generate taste-aware images with a single API call.

Authentication

All requests require an API key passed as a Bearer token in the Authorization header. Create API keys in your dashboard.

Header

Authorization: Bearer tm_live_your_key_here

Generate an Image

POST /api/v1/generate

Submit a brief and receive a task ID. The taste engine refines your brief, then generates the image asynchronously.

Request

curl -X POST https://api.thetastemachine.com/api/v1/generate \
  -H "Authorization: Bearer tm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "A minimal poster for a Tokyo coffee shop, warm tones, editorial feel",
    "model": "nano-banana-pro",
    "aspect_ratio": "3:4",
    "resolution": "2k",
    "taste": "default",
    "image_urls": ["https://example.com/reference.jpg"]
  }'

Response (202 Accepted)

{
  "task_id": "aBcDeFgHiJkLmNoP",
  "status": "queued",
  "estimated_time_seconds": 30,
  "credits": {
    "required": 10,
    "remaining": 830
  }
}

Parameters

Field	Type	Required	Description
brief	string	Yes	Describe the image you want.
model	string	No	"nano-banana-pro" or "nano-banana-2". Default: nano-banana-pro
aspect_ratio	string	No	Default: "1:1". Options: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9". nano-banana-2 also supports "1:4", "4:1", "1:8", "8:1".
resolution	string	No	"1k", "2k", or "4k". Default: 2k
taste	string	No	"default" or "realistic-photo". Default: default
image_urls	string[]	No	Array of publicly accessible image URLs to use as input references. Max 14 images.

Taste Profiles

The taste profile controls how the Taste Machine interprets your brief. Each profile brings a different aesthetic sensibility to the generation, shaping composition, colour direction, and visual tone.

Taste profiles are currently in public preview. We will be releasing additional profiles over time, and will offer custom training services for teams and studios that want to train a taste profile on their own creative direction.

defaultA versatile profile with a natural affinity for graphic and editorial work — posters, branding, packaging, and visual campaigns tend to perform especially well. Still effective across all use cases.

realistic-photoTuned for photorealistic output. Best suited for realistic photography, portraits, street scenes, and documentary-style imagery.

Poll for Results

GET /api/v1/generate?task_id=ID

Poll until status is "complete" or "failed". Recommended interval: 2 seconds.

Request

curl https://api.thetastemachine.com/api/v1/generate?task_id=aBcDeFgHiJkLmNoP \
  -H "Authorization: Bearer tm_live_your_key_here"

Response (processing)

{
  "task_id": "aBcDeFgHiJkLmNoP",
  "status": "processing"
}

Response (complete)

{
  "task_id": "aBcDeFgHiJkLmNoP",
  "status": "complete",
  "result": {
    "image_url": "https://cdn.thetastemachine.com/gen/abc123.png",
    "prompt_used": "A softly lit interior of a minimalist Tokyo kissaten...",
    "expires_at": "2026-04-14T00:00:00Z"
  },
  "credits_consumed": 10
}

Available Models

nano-banana-proBest general-purpose model. Advanced reasoning, highest quality. Recommended default.

nano-banana-2Fast, cost-efficient generation. Great for high-volume use.

Credit Costs

Credits vary by model and resolution. Insufficient credits will return a 402 response with the required and available amounts.

Model	Resolution	Credits	Description
nano-banana-pro	1k	10	Standard resolution — fast previews
nano-banana-pro	2k	10	High resolution — recommended default
nano-banana-pro	4k	15	Ultra-high resolution — print quality
nano-banana-2	1k	8	Standard resolution — fast previews
nano-banana-2	2k	9	High resolution — recommended default
nano-banana-2	4k	10	Ultra-high resolution — print quality

Rate Limits

API requests are rate-limited per API key. Current limits:

• 60 requests per minute per key
• 10 concurrent generations per key

Errors

Status	Meaning
401	Invalid or missing API key
400	Invalid request body or parameters
402	Insufficient credits
429	Rate limit exceeded
500	Internal server error

Ready to get started?

Get Your API Key Try the Demo