Maton

fal.ai

Access the fal.ai queue API with managed API key authentication. Run 1000+ AI models including image generation (Flux, SDXL), video generation (Minimax), image upscaling, text-to-speech, and more.

Reference

Submit Request

Submit a request to run a model. Returns immediately with a request ID.

POST /fal-ai/fal-ai/{model-id}
Content-Type: application/json

{
  "prompt": "model-specific parameters",
  ...
}

Response:

{
  "status": "IN_QUEUE",
  "request_id": "3229f185-a99a-48c0-a292-e25bf9baaeba",
  "response_url": "https://queue.fal.run/fal-ai/flux/requests/3229f185-a99a-48c0-a292-e25bf9baaeba",
  "status_url": "https://queue.fal.run/fal-ai/flux/requests/3229f185-a99a-48c0-a292-e25bf9baaeba/status",
  "cancel_url": "https://queue.fal.run/fal-ai/flux/requests/3229f185-a99a-48c0-a292-e25bf9baaeba/cancel",
  "queue_position": 0
}

Check Status

Poll for request status until completion.

GET /fal-ai/fal-ai/{model-id}/requests/{request_id}/status

Response (IN_PROGRESS):

{
  "status": "IN_PROGRESS",
  "request_id": "3229f185-a99a-48c0-a292-e25bf9baaeba"
}

Response (COMPLETED):

{
  "status": "COMPLETED",
  "request_id": "3229f185-a99a-48c0-a292-e25bf9baaeba",
  "metrics": {
    "inference_time": 0.3334658145904541
  }
}

Get Result

Retrieve the completed result.

GET /fal-ai/fal-ai/{model-id}/requests/{request_id}

Response (image generation):

{
  "images": [
    {
      "url": "https://v3b.fal.media/files/...",
      "width": 1024,
      "height": 1024,
      "content_type": "image/jpeg"
    }
  ],
  "timings": {
    "inference": 0.1587670766748488
  },
  "seed": 761506470,
  "prompt": "a tiny cute cat"
}

Cancel Request

Cancel a queued or in-progress request.

PUT /fal-ai/fal-ai/{model-id}/requests/{request_id}/cancel

Flux Schnell (Fast Image Generation)

python <<'EOF'
import urllib.request, os, json

data = json.dumps({
    "prompt": "a serene mountain landscape at sunset",
    "image_size": "landscape_16_9",
    "num_images": 1,
    "num_inference_steps": 4
}).encode()

req = urllib.request.Request('https://api.maton.ai/fal-ai/fal-ai/flux/schnell', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Parameters:

  • prompt (required): Text description of the image
  • image_size: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9
  • num_images: Number of images to generate (default: 1)
  • num_inference_steps: Number of steps (default: 4)
  • seed: Random seed for reproducibility

Fast SDXL (Stable Diffusion XL)

python <<'EOF'
import urllib.request, os, json

data = json.dumps({
    "prompt": "a futuristic city skyline at night",
    "negative_prompt": "blurry, low quality",
    "image_size": "landscape_16_9",
    "num_images": 1
}).encode()

req = urllib.request.Request('https://api.maton.ai/fal-ai/fal-ai/fast-sdxl', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Parameters:

  • prompt (required): Text description
  • negative_prompt: What to avoid in the image
  • image_size: Output dimensions
  • num_images: Number of images
  • guidance_scale: CFG scale (default: 7.5)
  • num_inference_steps: Number of steps

Clarity Upscaler (Image Upscaling)

python <<'EOF'
import urllib.request, os, json

data = json.dumps({
    "image_url": "https://example.com/image.jpg",
    "scale": 2
}).encode()

req = urllib.request.Request('https://api.maton.ai/fal-ai/fal-ai/clarity-upscaler', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Parameters:

  • image_url (required): URL of the image to upscale
  • scale: Upscale factor (2, 4)

Minimax Video Generation

python <<'EOF'
import urllib.request, os, json

data = json.dumps({
    "prompt": "A cat playing with a ball in slow motion"
}).encode()

req = urllib.request.Request('https://api.maton.ai/fal-ai/fal-ai/minimax/video-01', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

F5-TTS (Text-to-Speech)

python <<'EOF'
import urllib.request, os, json

data = json.dumps({
    "gen_text": "Hello world, this is a test of fal ai text to speech."
}).encode()

req = urllib.request.Request('https://api.maton.ai/fal-ai/fal-ai/f5-tts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Request Status Values

StatusDescription
IN_QUEUERequest received, waiting for runner
IN_PROGRESSModel is processing the request
COMPLETEDProcessing finished, result available
FAILEDProcessing failed (check error details)

Request Headers

HeaderDescription
X-Fal-Request-TimeoutServer-side deadline in seconds
X-Fal-Runner-HintSession affinity for routing
X-Fal-Queue-Prioritynormal (default) or low
X-Fal-No-RetryDisable automatic retries

Resources

PreviousExaNextFathom

On this page

Reference
Submit Request
Check Status
Get Result
Cancel Request
Flux Schnell (Fast Image Generation)
Fast SDXL (Stable Diffusion XL)
Clarity Upscaler (Image Upscaling)
Minimax Video Generation
F5-TTS (Text-to-Speech)
Request Status Values
Request Headers
Resources