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
labelandscorefor the answer, andlabels(every label with its score, best first) orscores(label to score). - Spans (entities, PII) are
{type, text, start, end, score}with character offsets into your input,endexclusive. - 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
flaggeduse thethresholdoption.
Media inputs
https://orhttp://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-1withContent-Type: image/jpegand 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=50andGET /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.