Docs

From key to first frame in five minutes.

One REST endpoint, one request shape and SDKs for Python and TypeScript. This guide covers everything you need for production.

Overview

Every request goes to https://api.monogram.dev/v1 and uses the same envelope: the model you want, an input object, and optional fallbacks and a webhook. Switching models never changes the shape of your code.

Images usually finish in seconds and come straight back. Video and other long renders run as jobs that you can wait on, poll or receive by webhook.

request.json

{
  "model": "provider/model-name",
  "input": {
    "prompt": "What you want to see"
  },
  "fallbacks": [
    "provider/another-model"
  ],
  "webhook_url": "https://example.com/hooks/monogram"
}

Authentication

Send your key as a bearer token in the Authorization header. Keys are created in the studio, can be scoped to a project and carry their own budget.

The SDKs read MONOGRAM_API_KEY from the environment. Keep the key on your server and never ship it in browser code.

terminal

# Keep your key on the server, never in browser code
export MONOGRAM_API_KEY="mk_live_..."

Your first image

Pick any image model from the roster and send a prompt. The response includes a URL for each output.

request.sh

curl https://api.monogram.dev/v1/generations \
  -H "Authorization: Bearer $MONOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bfl/flux-2-pro",
    "input": {
      "prompt": "A crystal perfume bottle on black marble, gold rim light, 1920s poster",
      "aspect_ratio": "4:5"
    }
  }'

Your first video

Video uses the same call with a video model. Add an image_url to animate a still, and set audio on models that generate sound.

request.sh

curl https://api.monogram.dev/v1/generations \
  -H "Authorization: Bearer $MONOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "input": {
      "prompt": "Slow dolly through a 1920s ballroom, chandeliers glowing, couples dancing",
      "duration": 5,
      "aspect_ratio": "16:9",
      "audio": true
    }
  }'

Jobs

Every generation has an ID and a status: queued, running, succeeded, failed or canceled. The SDK helper wait polls for you; with raw HTTP, fetch the generation until it settles.

poll.sh

curl https://api.monogram.dev/v1/generations/gen_01JDK8X7MZ \
  -H "Authorization: Bearer $MONOGRAM_API_KEY"

Webhooks

Add webhook_url to any request and Monogram calls it when the job settles. Each delivery is signed with your webhook secret in the Monogram-Signature header, so check it before trusting the payload.

generation.succeeded.json

{
  "type": "generation.succeeded",
  "created_at": "2026-10-22T09:15:11Z",
  "data": {
    "id": "gen_01JDK8X7MZ",
    "model": "google/veo-3.1",
    "status": "succeeded",
    "output": [
      {
        "url": "https://cdn.monogram.dev/gen_01JDK8X7MZ/0.mp4"
      }
    ]
  }
}

Running a skill

Skills run several models in sequence for one job. Call one by its name with the inputs listed on its skill page, and get back a run with the final output and every intermediate file.

run.sh

curl https://api.monogram.dev/v1/skills/product-shot/runs \
  -H "Authorization: Bearer $MONOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image_url": "https://files.example.com/sneaker.jpg",
      "scene": "Black marble plinth, soft gold rim light",
      "aspect_ratio": "4:5"
    }
  }'

Fallbacks

List backup models in fallbacks. If the first model is unavailable or over its time limit, the request moves down the list and the response names the model that answered. You can also set default fallbacks per project in the studio.

request.json

{
  "model": "google/veo-3.1",
  "fallbacks": [
    "openai/sora-2-pro",
    "kuaishou/kling-2.5-turbo"
  ],
  "input": {
    "prompt": "Slow dolly through a 1920s ballroom, chandeliers glowing",
    "duration": 8
  }
}

Errors

Errors use standard HTTP status codes and a JSON body with a stable code you can branch on. Send an Idempotency-Key header on retries so a repeated request never generates twice.

API error codes
Status	Code	Meaning
400	`invalid_input`	The input does not match what the model accepts. The message names the field.
401	`unauthorized`	The key is missing, revoked or mistyped.
402	`insufficient_balance`	Top up your balance or raise the budget on the key.
404	`model_not_found`	The model ID is not in the roster. Check it on the models page.
409	`idempotency_conflict`	The same Idempotency-Key was sent with a different body.
422	`content_rejected`	The provider declined the prompt or one of the input files.
429	`rate_limited`	Too many requests. Wait for the seconds in the Retry-After header.
503	`provider_unavailable`	The model is unavailable right now. Fallbacks route around it.

error.json

{
  "error": {
    "code": "invalid_input",
    "message": "duration must be 4, 6 or 8 for google/veo-3.1",
    "field": "input.duration"
  }
}

Ready for a key?

Tell us what you are building and we will set you up.

Request access