API Documentation

Authentication

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

Authorization: Bearer tm_live_your_key_here

Design Agent

POST /api/v1/agent

The full agentic pipeline behind the app: the design agent researches our taste corpus, develops a direction for your brief, and renders one or more finished designs. Each call is single-shot — one brief in, a set of images out. Runs take a few minutes; poll for the result.

curl -X POST https://www.thetastemachine.com/api/v1/agent \
  -H "Authorization: Bearer tm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "A launch poster for a matcha bar, riso print feel, playful type",
    "aspect_ratio": "3:4"
  }'

{
  "run_id": "api-mfx2k1-a1b2c3",
  "status": "processing"
}

Parameters

Poll for the run

GET /api/v1/agent?run_id=ID

Poll until status leaves "processing". Recommended interval: 5 seconds. If the brief was too ambiguous to design from, the run ends as "needs_clarification" with the agent's question in message — make a new request with a sharper brief (there is no multi-turn over the API).

curl "https://www.thetastemachine.com/api/v1/agent?run_id=api-mfx2k1-a1b2c3" \
  -H "Authorization: Bearer tm_live_your_key_here"

{
  "run_id": "api-mfx2k1-a1b2c3",
  "status": "complete",
  "images_generated": 2,
  "images": [
    { "image_url": "https://r2.thetastemachine.com/...", "model": "nano-banana-2-lite", "aspect_ratio": "3:4", "credits": 7 },
    { "image_url": "https://r2.thetastemachine.com/...", "model": "nano-banana-2-lite", "aspect_ratio": "3:4", "credits": 7 }
  ],
  "credits_consumed": 14,
  "message": "Delivered: a riso-textured launch poster..."
}

{
  "run_id": "api-mfx2k1-a1b2c3",
  "status": "needs_clarification",
  "images_generated": 0,
  "error": "NEEDS_CLARIFICATION",
  "message": "Should the poster lead with the store name or the opening date?"
}

Agent pricing

You are charged per delivered image — a run typically delivers 1–3 images (at most 6), and each image's cost depends on the image model the run used (reported per image in the poll response). The agent's reasoning steps are free — a run that delivers nothing costs nothing.

Rate Limits

Limits apply per account (all of an account's API keys and in-app usage share one budget):

• • Design agent: 10 new runs per minute, and at most 3 runs in progress at once
• • A rejected request returns 429 with retry_after_seconds and a Retry-After header where applicable

Errors