Great Work Labs

API reference

Base URL: https://labs.greatwork.company/v1. JSON in, JSON out. Authenticate with Authorization: Bearer gwl_... (or X-Api-Key).

Run a model

POST /v1/run

Field Required Description
model yes Model id like sieve-1, or the bare name sieve for the newest version.
input yes Text (string), a batch (array of strings), or media (URL, data URL, or multipart file).
options per model Named fields next to input, listed on each model's page. Unknown fields are rejected with unknown_param, so typos don't pass silently.

Shortcuts that do the same thing: POST /v1/models/{id}/run and POST /v1/{id} (e.g. POST /v1/sieve-1 with {"input": "..."}).

Response:

{
  "id": "run_...",
  "object": "run",
  "model": "veil-1",
  "created": 1763510400,
  "output": {
    "redacted": "Call [PERSON] at [PHONE]",
    "spans": [
      "..."
    ],
    "counts": {
      "person": 1,
      "phone": 1
    }
  },
  "usage": {
    "units": 1,
    "unit": "text",
    "cost_usd": "0.00002",
    "cost_micros": 20
  },
  "latency_ms": 41
}

Response headers: X-Request-Id (the run id), X-Cost-USD, X-Balance-USD (after this call), RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Output conventions

  • Classifications have label and score for the answer, and labels (every label with its score, best first) or scores (label to score).
  • Spans (entities, PII) are {type, text, start, end, score} with character offsets into your input, end exclusive.
  • Boxes are {x, y, width, height} in pixels of the original image.
  • Scores are probabilities from 0 to 1 unless a field says otherwise. Booleans like flagged use the threshold option.

Media inputs

  • https:// or http:// URLs on the public internet (we download them; private addresses are refused). 20-second download limit.
  • Data URLs: data:image/png;base64,....
  • Multipart: -F model=ink-1 -F input=@photo.jpg. Other options go in their own fields; arrays and objects as JSON strings.
  • Raw bytes: POST /v1/run?model=ink-1 with Content-Type: image/jpeg and the file as the body.
  • Images up to 10 MB; audio up to 25 MB and 5 minutes.

Cold starts

Models load on first use and stay loaded while they're busy. A call to a model nobody has used in a while takes 2 to 6 seconds while it loads, and its response includes "cold_start": true; calls after that take tens of milliseconds for text models. If you call a model rarely and latency matters, a cheap call at startup warms it.

Estimate a cost

POST /v1/estimate takes the same body as /v1/run and returns the most the call can cost, without running it or touching your balance. No key needed.

{
  "object": "estimate",
  "model": "sort-1",
  "units": 4,
  "unit": "label",
  "max_cost_usd": "0.00004",
  "max_cost_micros": 40,
  "note": "You're billed for the units the model actually uses, never more than this."
}

Models

  • GET /v1/models: every model with its price, category and modality. No key needed.
  • GET /v1/models/{id}: one model with options, output fields, limits, caveats and real example requests and outputs.

Account and usage

  • GET /v1/account: balance, month-to-date spend, monthly cap, auto top-up settings, and the calling key's own limit and spend.
  • GET /v1/usage?days=30: calls, units and cost per day per model.
  • GET /v1/runs?limit=50 and GET /v1/runs/{id}: recent calls (metadata only: we never store inputs or outputs).

Idempotency

Send Idempotency-Key: <any unique string> on a POST and a retry with the same key and body returns the first response (with Idempotent-Replayed: true) instead of running and charging again. Keys last 24 hours. The same key with a different body is a 409 idempotency_key_reused.

Rate limits

25 requests per second per account. Batch inputs count as one request, so a batch of 64 texts is the fastest way to process volume. Over the limit you get 429 rate_limited with Retry-After.

Errors

Every error has the same shape and an HTTP status that tells you what to do:

{
  "error": {
    "type": "payment_required",
    "code": "insufficient_balance",
    "message": "Not enough credit: this call can cost up to $0.00002 and the available balance is $0.0.",
    "add_credit_url": "https://labs.greatwork.company/dashboard/billing",
    "docs_url": "https://labs.greatwork.company/docs/errors#insufficient_balance",
    "request_id": "req_..."
  }
}

See all error codes. Errors are never charged.

Billing rules

  • Before a call runs we hold its maximum cost (from the input size). You're billed the units the model used, never more than the hold.
  • Failed calls (4xx and 5xx) cost nothing.
  • Audio holds the cost of 5 minutes and settles to the real duration.