@mccaskie-labs/workbench-config 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/capabilities/gateway.json +9 -3
- package/capabilities/image-search.json +130 -0
- package/capabilities/image-search.md +19 -0
- package/capabilities/images.json +208 -0
- package/capabilities/images.md +27 -0
- package/dist/capabilities.gen.d.ts +281 -2
- package/dist/capabilities.gen.js +380 -2
- package/dist/capability-schema.d.ts +25 -0
- package/dist/capability-schema.js +13 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @mccaskie-labs/workbench-config
|
|
2
2
|
|
|
3
|
+
## 0.1.3
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- The `gateway` manifest is now `built` (step 4.5): the `X-Workbench-Env` request header, the per-key rate limit (300 a minute), the `not_found` and `internal_error` codes, and the `gateway.server-timing` probe.
|
|
8
|
+
|
|
9
|
+
## 0.1.2
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- Add the images and image-search manifests (planned), with their `allowed` schemas.
|
|
14
|
+
|
|
3
15
|
## 0.1.1
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"component": "gateway",
|
|
5
5
|
"title": "Workbench Gateway: keys, headers, budgets and errors",
|
|
6
6
|
"summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
|
|
7
|
-
"status": "
|
|
7
|
+
"status": "built",
|
|
8
8
|
"surfaces": {
|
|
9
9
|
"gateway": ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"],
|
|
10
10
|
"package": ["DEFAULT_GATEWAY_URL"]
|
|
@@ -38,7 +38,8 @@
|
|
|
38
38
|
{ "name": "X-Workbench-Job", "required": true, "pattern": "^[a-z0-9._-]{1,64}$", "description": "What the call is for, e.g. article.write. Recorded with usage" },
|
|
39
39
|
{ "name": "X-Workbench-Prompt-Version", "required": false, "description": "The app's prompt version, recorded with usage (audit F17)" },
|
|
40
40
|
{ "name": "X-Workbench-Subject", "required": false, "pattern": "^[a-z0-9_-]+:[^\\s]{1,128}$", "description": "type:id of the thing the call is about" },
|
|
41
|
-
{ "name": "Idempotency-Key", "required": false, "description": "Email only: a repeat within 24 hours returns the stored result" }
|
|
41
|
+
{ "name": "Idempotency-Key", "required": false, "description": "Email only: a repeat within 24 hours returns the stored result" },
|
|
42
|
+
{ "name": "X-Workbench-Env", "required": false, "pattern": "^(development|staging|production)$", "description": "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised" }
|
|
42
43
|
],
|
|
43
44
|
"response_headers": ["X-Workbench-Request-Id", "Server-Timing"],
|
|
44
45
|
"server_timing_metrics": ["gw", "vendor_fb", "vendor", "total"]
|
|
@@ -46,6 +47,7 @@
|
|
|
46
47
|
"limits": [
|
|
47
48
|
{ "id": "gateway.key-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
|
|
48
49
|
{ "id": "gateway.budget-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
|
|
50
|
+
{ "id": "gateway.rate-limit", "value": 300, "unit": "requests", "per": "minute per key", "enforced_by": "gateway", "refusal": "rate_limited" },
|
|
49
51
|
{ "id": "gateway.job-format", "value": "[a-z0-9._-]{1,64}", "unit": "pattern", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" }
|
|
50
52
|
],
|
|
51
53
|
"errors": [
|
|
@@ -56,15 +58,19 @@
|
|
|
56
58
|
{ "code": "rate_limited", "http": 429, "retryable": true, "meaning": "Per-key rate limit; it stops runaway loops, budgets limit spend" },
|
|
57
59
|
{ "code": "not_available", "http": 501, "retryable": false, "meaning": "Not built yet, e.g. bulk email" },
|
|
58
60
|
{ "code": "upstream_error", "http": 502, "retryable": true, "meaning": "The vendor failed after the Gateway's retries" },
|
|
59
|
-
{ "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "The vendor didn't answer in time" }
|
|
61
|
+
{ "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "The vendor didn't answer in time" },
|
|
62
|
+
{ "code": "not_found", "http": 404, "retryable": false, "meaning": "No such path. Every documented endpoint checks the key and scope first, even one not built yet" },
|
|
63
|
+
{ "code": "internal_error", "http": 500, "retryable": true, "meaning": "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor" }
|
|
60
64
|
],
|
|
61
65
|
"rules": [
|
|
62
66
|
{ "id": "gateway.no-vendor-keys", "kind": "must_not", "text": "Hold a vendor key (Anthropic, Google, OpenAI, Serper, email) in an app. The Gateway key is the only Workbench credential an app has.", "enforced_by": "review", "probe": "gateway.no-vendor-keys.scan" },
|
|
63
67
|
{ "id": "gateway.key-per-environment", "kind": "must", "text": "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.", "enforced_by": "gateway", "probe": "gateway.wrong-environment" },
|
|
68
|
+
{ "id": "gateway.timing-headers", "kind": "must", "text": "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.", "enforced_by": "gateway", "probe": "gateway.server-timing" },
|
|
64
69
|
{ "id": "gateway.request-id-kept", "kind": "must", "text": "Keep X-Workbench-Request-Id with any output stored or any error logged, so it can be matched to a usage row.", "enforced_by": "review", "probe": "gateway.health" }
|
|
65
70
|
],
|
|
66
71
|
"probes": [
|
|
67
72
|
{ "id": "gateway.health", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
|
|
73
|
+
{ "id": "gateway.server-timing", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
|
|
68
74
|
{ "id": "gateway.bad-key", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "smoke": true, "cost_hint_usd": 0 },
|
|
69
75
|
{ "id": "gateway.wrong-scope", "half": "runtime", "expect": "refused_as_expected", "refusal": "forbidden_scope", "cost_hint_usd": 0 },
|
|
70
76
|
{ "id": "gateway.wrong-environment", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "cost_hint_usd": 0 },
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "./schema.json",
|
|
3
|
+
"format": 1,
|
|
4
|
+
"component": "image-search",
|
|
5
|
+
"title": "Image search through the Gateway",
|
|
6
|
+
"summary": "Web image search through Serper, normalised to one result shape and metered against the project's budget. Apps never hold a Serper key.",
|
|
7
|
+
"status": "planned",
|
|
8
|
+
"surfaces": {
|
|
9
|
+
"gateway": [
|
|
10
|
+
"POST /v1/images/search"
|
|
11
|
+
],
|
|
12
|
+
"package": [
|
|
13
|
+
"Ai.images.search"
|
|
14
|
+
]
|
|
15
|
+
},
|
|
16
|
+
"config": [
|
|
17
|
+
{
|
|
18
|
+
"name": "WORKBENCH_GATEWAY_KEY",
|
|
19
|
+
"required": true,
|
|
20
|
+
"secret": true,
|
|
21
|
+
"environments": [
|
|
22
|
+
"staging",
|
|
23
|
+
"production"
|
|
24
|
+
],
|
|
25
|
+
"description": "Project key with the search scope, delivered as a Worker secret by gw_key_issue"
|
|
26
|
+
}
|
|
27
|
+
],
|
|
28
|
+
"allowed": {
|
|
29
|
+
"providers": [
|
|
30
|
+
"serper"
|
|
31
|
+
],
|
|
32
|
+
"result_fields": [
|
|
33
|
+
"title",
|
|
34
|
+
"image_url",
|
|
35
|
+
"thumbnail_url",
|
|
36
|
+
"width",
|
|
37
|
+
"height",
|
|
38
|
+
"source",
|
|
39
|
+
"page_url"
|
|
40
|
+
],
|
|
41
|
+
"required_headers": [
|
|
42
|
+
"X-Workbench-Job"
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
"limits": [
|
|
46
|
+
{
|
|
47
|
+
"id": "image-search.num",
|
|
48
|
+
"value": "1-100",
|
|
49
|
+
"unit": "results",
|
|
50
|
+
"per": "request",
|
|
51
|
+
"enforced_by": "gateway",
|
|
52
|
+
"refusal": "invalid_request"
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"id": "image-search.num-default",
|
|
56
|
+
"value": 10,
|
|
57
|
+
"unit": "results",
|
|
58
|
+
"per": "request",
|
|
59
|
+
"enforced_by": "gateway"
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"id": "image-search.upstream-timeout",
|
|
63
|
+
"value": 90,
|
|
64
|
+
"unit": "seconds",
|
|
65
|
+
"per": "request",
|
|
66
|
+
"enforced_by": "gateway",
|
|
67
|
+
"refusal": "upstream_timeout"
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
"errors": [
|
|
71
|
+
{
|
|
72
|
+
"code": "invalid_request",
|
|
73
|
+
"http": 400,
|
|
74
|
+
"retryable": false,
|
|
75
|
+
"meaning": "An empty query or a bad num, gl or hl"
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
"code": "budget_exceeded",
|
|
79
|
+
"http": 402,
|
|
80
|
+
"retryable": false,
|
|
81
|
+
"meaning": "Enforced monthly budget reached"
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
"code": "upstream_error",
|
|
85
|
+
"http": 502,
|
|
86
|
+
"retryable": true,
|
|
87
|
+
"meaning": "Serper failed after the Gateway's retries"
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"code": "upstream_timeout",
|
|
91
|
+
"http": 504,
|
|
92
|
+
"retryable": true,
|
|
93
|
+
"meaning": "Serper didn't answer within 90 seconds"
|
|
94
|
+
}
|
|
95
|
+
],
|
|
96
|
+
"rules": [
|
|
97
|
+
{
|
|
98
|
+
"id": "image-search.https-only",
|
|
99
|
+
"kind": "must",
|
|
100
|
+
"text": "Use only https image and page URLs from the results; the Gateway drops any result without one.",
|
|
101
|
+
"enforced_by": "gateway",
|
|
102
|
+
"probe": "image-search.serper"
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
"id": "image-search.licence-check",
|
|
106
|
+
"kind": "must",
|
|
107
|
+
"text": "Treat results as leads, not as images the app may republish. Check the source's licence before storing or showing one.",
|
|
108
|
+
"enforced_by": "review",
|
|
109
|
+
"probe": "image-search.serper"
|
|
110
|
+
}
|
|
111
|
+
],
|
|
112
|
+
"examples": [
|
|
113
|
+
{
|
|
114
|
+
"id": "image-search.example.search",
|
|
115
|
+
"title": "Search for images",
|
|
116
|
+
"lang": "ts",
|
|
117
|
+
"probe": "image-search.serper",
|
|
118
|
+
"code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst results = await ai.images.search({ q: 'Mayon volcano', job: 'editor.image-search', num: 10 })"
|
|
119
|
+
}
|
|
120
|
+
],
|
|
121
|
+
"probes": [
|
|
122
|
+
{
|
|
123
|
+
"id": "image-search.serper",
|
|
124
|
+
"half": "runtime",
|
|
125
|
+
"expect": "pass",
|
|
126
|
+
"smoke": true,
|
|
127
|
+
"cost_hint_usd": 0.001
|
|
128
|
+
}
|
|
129
|
+
]
|
|
130
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Image search
|
|
2
|
+
|
|
3
|
+
Apps search the web for images through the Gateway with `ai.images.search` from `@mccaskie-labs/workbench-ai`, or `POST /v1/images/search` directly. The Gateway holds the Serper key; the app's Gateway key needs the `search` scope.
|
|
4
|
+
|
|
5
|
+
## Request
|
|
6
|
+
|
|
7
|
+
`q` is required. `num` is 1 to 100 and defaults to 10. `gl` (country) and `hl` (language) pass through to Serper, for example `gl: 'ph', hl: 'en'`.
|
|
8
|
+
|
|
9
|
+
## Results
|
|
10
|
+
|
|
11
|
+
Each result is `{ title, image_url, thumbnail_url, width, height, source, page_url }`. Results without an https image URL are dropped. Filtering by size, shape or site is the app's job: ask for more results than you need and filter them.
|
|
12
|
+
|
|
13
|
+
## Cost
|
|
14
|
+
|
|
15
|
+
Serper bills in credits of US$0.001: 1 credit for up to 10 results, 2 for more. Only searches Serper answers are recorded as usage.
|
|
16
|
+
|
|
17
|
+
## Licences
|
|
18
|
+
|
|
19
|
+
A result is a lead, not permission. Check the source's licence before the app stores or shows an image it found.
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "./schema.json",
|
|
3
|
+
"format": 1,
|
|
4
|
+
"component": "images",
|
|
5
|
+
"title": "Image generation through the Gateway",
|
|
6
|
+
"summary": "One image per call from Gemini or OpenAI, chosen by a Workbench alias and metered against the project's budget. Apps never hold a Google or OpenAI key, and the Gateway never falls back to another provider.",
|
|
7
|
+
"status": "planned",
|
|
8
|
+
"surfaces": {
|
|
9
|
+
"gateway": [
|
|
10
|
+
"POST /v1/images/generate"
|
|
11
|
+
],
|
|
12
|
+
"package": [
|
|
13
|
+
"Ai.images.generate"
|
|
14
|
+
]
|
|
15
|
+
},
|
|
16
|
+
"config": [
|
|
17
|
+
{
|
|
18
|
+
"name": "WORKBENCH_GATEWAY_KEY",
|
|
19
|
+
"required": true,
|
|
20
|
+
"secret": true,
|
|
21
|
+
"environments": [
|
|
22
|
+
"staging",
|
|
23
|
+
"production"
|
|
24
|
+
],
|
|
25
|
+
"description": "Project key with the images scope, delivered as a Worker secret by gw_key_issue"
|
|
26
|
+
}
|
|
27
|
+
],
|
|
28
|
+
"allowed": {
|
|
29
|
+
"aliases": [
|
|
30
|
+
{
|
|
31
|
+
"alias": "image-default",
|
|
32
|
+
"provider": "google",
|
|
33
|
+
"default_model": "gemini-3.1-flash-image"
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"alias": "image-pro",
|
|
37
|
+
"provider": "google",
|
|
38
|
+
"default_model": "gemini-3-pro-image"
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"alias": "image-openai",
|
|
42
|
+
"provider": "openai",
|
|
43
|
+
"default_model": "gpt-image-2.5-sunburst"
|
|
44
|
+
}
|
|
45
|
+
],
|
|
46
|
+
"aspect_ratios": [
|
|
47
|
+
"1:1",
|
|
48
|
+
"3:2",
|
|
49
|
+
"2:3",
|
|
50
|
+
"4:3",
|
|
51
|
+
"3:4",
|
|
52
|
+
"16:9",
|
|
53
|
+
"9:16"
|
|
54
|
+
],
|
|
55
|
+
"reference_providers": [
|
|
56
|
+
"google"
|
|
57
|
+
],
|
|
58
|
+
"reference_mime_types": [
|
|
59
|
+
"image/png",
|
|
60
|
+
"image/jpeg",
|
|
61
|
+
"image/webp"
|
|
62
|
+
],
|
|
63
|
+
"output_mime_types": [
|
|
64
|
+
"image/png",
|
|
65
|
+
"image/jpeg"
|
|
66
|
+
],
|
|
67
|
+
"required_headers": [
|
|
68
|
+
"X-Workbench-Job"
|
|
69
|
+
]
|
|
70
|
+
},
|
|
71
|
+
"limits": [
|
|
72
|
+
{
|
|
73
|
+
"id": "images.per-call",
|
|
74
|
+
"value": 1,
|
|
75
|
+
"unit": "images",
|
|
76
|
+
"per": "request",
|
|
77
|
+
"enforced_by": "gateway"
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
"id": "images.request-size",
|
|
81
|
+
"value": 20971520,
|
|
82
|
+
"unit": "bytes",
|
|
83
|
+
"per": "request",
|
|
84
|
+
"enforced_by": "gateway",
|
|
85
|
+
"refusal": "invalid_request"
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
"id": "images.upstream-timeout",
|
|
89
|
+
"value": 240,
|
|
90
|
+
"unit": "seconds",
|
|
91
|
+
"per": "request",
|
|
92
|
+
"enforced_by": "gateway",
|
|
93
|
+
"refusal": "upstream_timeout"
|
|
94
|
+
}
|
|
95
|
+
],
|
|
96
|
+
"errors": [
|
|
97
|
+
{
|
|
98
|
+
"code": "model_not_allowed",
|
|
99
|
+
"http": 400,
|
|
100
|
+
"retryable": false,
|
|
101
|
+
"meaning": "Not an image alias"
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
"code": "invalid_request",
|
|
105
|
+
"http": 400,
|
|
106
|
+
"retryable": false,
|
|
107
|
+
"meaning": "A bad aspect ratio, prompt or reference, or a reference on an OpenAI model"
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"code": "budget_exceeded",
|
|
111
|
+
"http": 402,
|
|
112
|
+
"retryable": false,
|
|
113
|
+
"meaning": "Enforced monthly budget reached"
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"code": "upstream_error",
|
|
117
|
+
"http": 502,
|
|
118
|
+
"retryable": true,
|
|
119
|
+
"meaning": "The provider failed or returned no image after the Gateway's retries"
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"code": "upstream_timeout",
|
|
123
|
+
"http": 504,
|
|
124
|
+
"retryable": true,
|
|
125
|
+
"meaning": "The provider didn't return an image within 4 minutes"
|
|
126
|
+
}
|
|
127
|
+
],
|
|
128
|
+
"rules": [
|
|
129
|
+
{
|
|
130
|
+
"id": "images.aliases-only",
|
|
131
|
+
"kind": "must",
|
|
132
|
+
"text": "Ask for an image alias (image-default, image-pro or image-openai), never a provider model id.",
|
|
133
|
+
"enforced_by": "gateway",
|
|
134
|
+
"probe": "images.generate.image-default"
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"id": "images.references-google-only",
|
|
138
|
+
"kind": "must_not",
|
|
139
|
+
"text": "Send reference images to an OpenAI alias. The Gateway refuses it with invalid_request rather than dropping them.",
|
|
140
|
+
"enforced_by": "gateway",
|
|
141
|
+
"probe": "images.generate.references-openai-refused"
|
|
142
|
+
},
|
|
143
|
+
{
|
|
144
|
+
"id": "images.no-silent-fallback",
|
|
145
|
+
"kind": "must_not",
|
|
146
|
+
"text": "Expect another provider to step in when one fails. The alias decides the provider; a failure is an error.",
|
|
147
|
+
"enforced_by": "gateway",
|
|
148
|
+
"probe": "images.generate.image-openai"
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
"id": "images.store-resolved-model",
|
|
152
|
+
"kind": "must",
|
|
153
|
+
"text": "Store the resolved model and request id with any image kept.",
|
|
154
|
+
"enforced_by": "review",
|
|
155
|
+
"probe": "images.generate.image-pro"
|
|
156
|
+
}
|
|
157
|
+
],
|
|
158
|
+
"examples": [
|
|
159
|
+
{
|
|
160
|
+
"id": "images.example.generate",
|
|
161
|
+
"title": "Generate one image",
|
|
162
|
+
"lang": "ts",
|
|
163
|
+
"probe": "images.generate.image-default",
|
|
164
|
+
"code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst img = await ai.images.generate({ prompt, aspectRatio: '3:2', job: 'article.hero' })\nawait env.IMAGES.put(key, img.bytes, { httpMetadata: { contentType: img.mimeType }, customMetadata: { model: img.model, requestId: img.requestId } })"
|
|
165
|
+
},
|
|
166
|
+
{
|
|
167
|
+
"id": "images.example.reference",
|
|
168
|
+
"title": "Generate from a reference image (Google aliases only)",
|
|
169
|
+
"lang": "ts",
|
|
170
|
+
"probe": "images.generate.references-google",
|
|
171
|
+
"code": "const img = await ai.images.generate({ prompt: 'The same scene at dusk', aspectRatio: '1:1', job: 'article.hero', model: 'image-default', references: [{ bytes, mimeType: 'image/png' }] })"
|
|
172
|
+
}
|
|
173
|
+
],
|
|
174
|
+
"probes": [
|
|
175
|
+
{
|
|
176
|
+
"id": "images.generate.image-default",
|
|
177
|
+
"half": "runtime",
|
|
178
|
+
"expect": "pass",
|
|
179
|
+
"smoke": true,
|
|
180
|
+
"cost_hint_usd": 0.067
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
"id": "images.generate.image-pro",
|
|
184
|
+
"half": "runtime",
|
|
185
|
+
"expect": "pass",
|
|
186
|
+
"cost_hint_usd": 0.134
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
"id": "images.generate.image-openai",
|
|
190
|
+
"half": "runtime",
|
|
191
|
+
"expect": "pass",
|
|
192
|
+
"cost_hint_usd": 0.011
|
|
193
|
+
},
|
|
194
|
+
{
|
|
195
|
+
"id": "images.generate.references-google",
|
|
196
|
+
"half": "runtime",
|
|
197
|
+
"expect": "pass",
|
|
198
|
+
"cost_hint_usd": 0.07
|
|
199
|
+
},
|
|
200
|
+
{
|
|
201
|
+
"id": "images.generate.references-openai-refused",
|
|
202
|
+
"half": "runtime",
|
|
203
|
+
"expect": "refused_as_expected",
|
|
204
|
+
"refusal": "invalid_request",
|
|
205
|
+
"cost_hint_usd": 0
|
|
206
|
+
}
|
|
207
|
+
]
|
|
208
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Images
|
|
2
|
+
|
|
3
|
+
Apps generate images through the Gateway with `ai.images.generate` from `@mccaskie-labs/workbench-ai`, or `POST /v1/images/generate` directly. The Gateway holds the Google and OpenAI keys; the app holds only its Gateway key, which needs the `images` scope.
|
|
4
|
+
|
|
5
|
+
## Aliases
|
|
6
|
+
|
|
7
|
+
Ask for an alias, never a provider model id. The alias decides the provider, and the response names the model it resolved to.
|
|
8
|
+
|
|
9
|
+
| Alias | Provider | Model | List price per image |
|
|
10
|
+
| --- | --- | --- | --- |
|
|
11
|
+
| `image-default` | Google | `gemini-3.1-flash-image` (Nano Banana 2) | about US$0.067 at 1K |
|
|
12
|
+
| `image-pro` | Google | `gemini-3-pro-image` (Nano Banana Pro) | about US$0.134 at 1K |
|
|
13
|
+
| `image-openai` | OpenAI | `gpt-image-2.5-sunburst`, medium quality | US$0.011 |
|
|
14
|
+
|
|
15
|
+
Google images are charged from the token counts in the response when it has them, and at the list price when it doesn't. There is no automatic fallback: if `image-default` fails, the call fails, and the app decides whether to try another alias.
|
|
16
|
+
|
|
17
|
+
## Shape and size
|
|
18
|
+
|
|
19
|
+
One image per call. `aspect_ratio` is one of `1:1 3:2 2:3 4:3 3:4 16:9 9:16`. Google models make 1K images (3:2 is 1264×848). OpenAI makes one of its three sizes, the nearest to the ratio asked for (1024×1024, 1536×1024 or 1024×1536), so check the bytes' real size if the shape matters.
|
|
20
|
+
|
|
21
|
+
## References
|
|
22
|
+
|
|
23
|
+
Reference images (`references`, up to 20 MB of request in total) go to Google aliases only. Sending one to `image-openai` is refused with `invalid_request` rather than quietly dropped.
|
|
24
|
+
|
|
25
|
+
## Keep the provenance
|
|
26
|
+
|
|
27
|
+
Store the resolved model and the request id with any image you keep (R2 custom metadata works), so a usage row and a picture can be matched later.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const MANIFEST_VERSION: "
|
|
1
|
+
export declare const MANIFEST_VERSION: "491c578e91bc";
|
|
2
2
|
export declare const capabilities: {
|
|
3
3
|
readonly ai: {
|
|
4
4
|
readonly $schema: "./schema.json";
|
|
@@ -214,7 +214,7 @@ export declare const capabilities: {
|
|
|
214
214
|
readonly component: "gateway";
|
|
215
215
|
readonly title: "Workbench Gateway: keys, headers, budgets and errors";
|
|
216
216
|
readonly summary: "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.";
|
|
217
|
-
readonly status: "
|
|
217
|
+
readonly status: "built";
|
|
218
218
|
readonly surfaces: {
|
|
219
219
|
readonly gateway: readonly ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"];
|
|
220
220
|
readonly package: readonly ["DEFAULT_GATEWAY_URL"];
|
|
@@ -267,6 +267,11 @@ export declare const capabilities: {
|
|
|
267
267
|
readonly name: "Idempotency-Key";
|
|
268
268
|
readonly required: false;
|
|
269
269
|
readonly description: "Email only: a repeat within 24 hours returns the stored result";
|
|
270
|
+
}, {
|
|
271
|
+
readonly name: "X-Workbench-Env";
|
|
272
|
+
readonly required: false;
|
|
273
|
+
readonly pattern: "^(development|staging|production)$";
|
|
274
|
+
readonly description: "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised";
|
|
270
275
|
}];
|
|
271
276
|
readonly response_headers: readonly ["X-Workbench-Request-Id", "Server-Timing"];
|
|
272
277
|
readonly server_timing_metrics: readonly ["gw", "vendor_fb", "vendor", "total"];
|
|
@@ -283,6 +288,13 @@ export declare const capabilities: {
|
|
|
283
288
|
readonly unit: "seconds";
|
|
284
289
|
readonly per: "isolate";
|
|
285
290
|
readonly enforced_by: "gateway";
|
|
291
|
+
}, {
|
|
292
|
+
readonly id: "gateway.rate-limit";
|
|
293
|
+
readonly value: 300;
|
|
294
|
+
readonly unit: "requests";
|
|
295
|
+
readonly per: "minute per key";
|
|
296
|
+
readonly enforced_by: "gateway";
|
|
297
|
+
readonly refusal: "rate_limited";
|
|
286
298
|
}, {
|
|
287
299
|
readonly id: "gateway.job-format";
|
|
288
300
|
readonly value: "[a-z0-9._-]{1,64}";
|
|
@@ -331,6 +343,16 @@ export declare const capabilities: {
|
|
|
331
343
|
readonly http: 504;
|
|
332
344
|
readonly retryable: true;
|
|
333
345
|
readonly meaning: "The vendor didn't answer in time";
|
|
346
|
+
}, {
|
|
347
|
+
readonly code: "not_found";
|
|
348
|
+
readonly http: 404;
|
|
349
|
+
readonly retryable: false;
|
|
350
|
+
readonly meaning: "No such path. Every documented endpoint checks the key and scope first, even one not built yet";
|
|
351
|
+
}, {
|
|
352
|
+
readonly code: "internal_error";
|
|
353
|
+
readonly http: 500;
|
|
354
|
+
readonly retryable: true;
|
|
355
|
+
readonly meaning: "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor";
|
|
334
356
|
}];
|
|
335
357
|
readonly rules: readonly [{
|
|
336
358
|
readonly id: "gateway.no-vendor-keys";
|
|
@@ -344,6 +366,12 @@ export declare const capabilities: {
|
|
|
344
366
|
readonly text: "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.";
|
|
345
367
|
readonly enforced_by: "gateway";
|
|
346
368
|
readonly probe: "gateway.wrong-environment";
|
|
369
|
+
}, {
|
|
370
|
+
readonly id: "gateway.timing-headers";
|
|
371
|
+
readonly kind: "must";
|
|
372
|
+
readonly text: "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.";
|
|
373
|
+
readonly enforced_by: "gateway";
|
|
374
|
+
readonly probe: "gateway.server-timing";
|
|
347
375
|
}, {
|
|
348
376
|
readonly id: "gateway.request-id-kept";
|
|
349
377
|
readonly kind: "must";
|
|
@@ -357,6 +385,12 @@ export declare const capabilities: {
|
|
|
357
385
|
readonly expect: "pass";
|
|
358
386
|
readonly smoke: true;
|
|
359
387
|
readonly cost_hint_usd: 0;
|
|
388
|
+
}, {
|
|
389
|
+
readonly id: "gateway.server-timing";
|
|
390
|
+
readonly half: "runtime";
|
|
391
|
+
readonly expect: "pass";
|
|
392
|
+
readonly smoke: true;
|
|
393
|
+
readonly cost_hint_usd: 0;
|
|
360
394
|
}, {
|
|
361
395
|
readonly id: "gateway.bad-key";
|
|
362
396
|
readonly half: "runtime";
|
|
@@ -398,6 +432,251 @@ export declare const capabilities: {
|
|
|
398
432
|
readonly note: "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets";
|
|
399
433
|
}];
|
|
400
434
|
};
|
|
435
|
+
readonly "image-search": {
|
|
436
|
+
readonly $schema: "./schema.json";
|
|
437
|
+
readonly format: 1;
|
|
438
|
+
readonly component: "image-search";
|
|
439
|
+
readonly title: "Image search through the Gateway";
|
|
440
|
+
readonly summary: "Web image search through Serper, normalised to one result shape and metered against the project's budget. Apps never hold a Serper key.";
|
|
441
|
+
readonly status: "planned";
|
|
442
|
+
readonly surfaces: {
|
|
443
|
+
readonly gateway: readonly ["POST /v1/images/search"];
|
|
444
|
+
readonly package: readonly ["Ai.images.search"];
|
|
445
|
+
};
|
|
446
|
+
readonly config: readonly [{
|
|
447
|
+
readonly name: "WORKBENCH_GATEWAY_KEY";
|
|
448
|
+
readonly required: true;
|
|
449
|
+
readonly secret: true;
|
|
450
|
+
readonly environments: readonly ["staging", "production"];
|
|
451
|
+
readonly description: "Project key with the search scope, delivered as a Worker secret by gw_key_issue";
|
|
452
|
+
}];
|
|
453
|
+
readonly allowed: {
|
|
454
|
+
readonly providers: readonly ["serper"];
|
|
455
|
+
readonly result_fields: readonly ["title", "image_url", "thumbnail_url", "width", "height", "source", "page_url"];
|
|
456
|
+
readonly required_headers: readonly ["X-Workbench-Job"];
|
|
457
|
+
};
|
|
458
|
+
readonly limits: readonly [{
|
|
459
|
+
readonly id: "image-search.num";
|
|
460
|
+
readonly value: "1-100";
|
|
461
|
+
readonly unit: "results";
|
|
462
|
+
readonly per: "request";
|
|
463
|
+
readonly enforced_by: "gateway";
|
|
464
|
+
readonly refusal: "invalid_request";
|
|
465
|
+
}, {
|
|
466
|
+
readonly id: "image-search.num-default";
|
|
467
|
+
readonly value: 10;
|
|
468
|
+
readonly unit: "results";
|
|
469
|
+
readonly per: "request";
|
|
470
|
+
readonly enforced_by: "gateway";
|
|
471
|
+
}, {
|
|
472
|
+
readonly id: "image-search.upstream-timeout";
|
|
473
|
+
readonly value: 90;
|
|
474
|
+
readonly unit: "seconds";
|
|
475
|
+
readonly per: "request";
|
|
476
|
+
readonly enforced_by: "gateway";
|
|
477
|
+
readonly refusal: "upstream_timeout";
|
|
478
|
+
}];
|
|
479
|
+
readonly errors: readonly [{
|
|
480
|
+
readonly code: "invalid_request";
|
|
481
|
+
readonly http: 400;
|
|
482
|
+
readonly retryable: false;
|
|
483
|
+
readonly meaning: "An empty query or a bad num, gl or hl";
|
|
484
|
+
}, {
|
|
485
|
+
readonly code: "budget_exceeded";
|
|
486
|
+
readonly http: 402;
|
|
487
|
+
readonly retryable: false;
|
|
488
|
+
readonly meaning: "Enforced monthly budget reached";
|
|
489
|
+
}, {
|
|
490
|
+
readonly code: "upstream_error";
|
|
491
|
+
readonly http: 502;
|
|
492
|
+
readonly retryable: true;
|
|
493
|
+
readonly meaning: "Serper failed after the Gateway's retries";
|
|
494
|
+
}, {
|
|
495
|
+
readonly code: "upstream_timeout";
|
|
496
|
+
readonly http: 504;
|
|
497
|
+
readonly retryable: true;
|
|
498
|
+
readonly meaning: "Serper didn't answer within 90 seconds";
|
|
499
|
+
}];
|
|
500
|
+
readonly rules: readonly [{
|
|
501
|
+
readonly id: "image-search.https-only";
|
|
502
|
+
readonly kind: "must";
|
|
503
|
+
readonly text: "Use only https image and page URLs from the results; the Gateway drops any result without one.";
|
|
504
|
+
readonly enforced_by: "gateway";
|
|
505
|
+
readonly probe: "image-search.serper";
|
|
506
|
+
}, {
|
|
507
|
+
readonly id: "image-search.licence-check";
|
|
508
|
+
readonly kind: "must";
|
|
509
|
+
readonly text: "Treat results as leads, not as images the app may republish. Check the source's licence before storing or showing one.";
|
|
510
|
+
readonly enforced_by: "review";
|
|
511
|
+
readonly probe: "image-search.serper";
|
|
512
|
+
}];
|
|
513
|
+
readonly examples: readonly [{
|
|
514
|
+
readonly id: "image-search.example.search";
|
|
515
|
+
readonly title: "Search for images";
|
|
516
|
+
readonly lang: "ts";
|
|
517
|
+
readonly code: "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst results = await ai.images.search({ q: 'Mayon volcano', job: 'editor.image-search', num: 10 })";
|
|
518
|
+
readonly probe: "image-search.serper";
|
|
519
|
+
}];
|
|
520
|
+
readonly probes: readonly [{
|
|
521
|
+
readonly id: "image-search.serper";
|
|
522
|
+
readonly half: "runtime";
|
|
523
|
+
readonly expect: "pass";
|
|
524
|
+
readonly smoke: true;
|
|
525
|
+
readonly cost_hint_usd: 0.001;
|
|
526
|
+
}];
|
|
527
|
+
};
|
|
528
|
+
readonly images: {
|
|
529
|
+
readonly $schema: "./schema.json";
|
|
530
|
+
readonly format: 1;
|
|
531
|
+
readonly component: "images";
|
|
532
|
+
readonly title: "Image generation through the Gateway";
|
|
533
|
+
readonly summary: "One image per call from Gemini or OpenAI, chosen by a Workbench alias and metered against the project's budget. Apps never hold a Google or OpenAI key, and the Gateway never falls back to another provider.";
|
|
534
|
+
readonly status: "planned";
|
|
535
|
+
readonly surfaces: {
|
|
536
|
+
readonly gateway: readonly ["POST /v1/images/generate"];
|
|
537
|
+
readonly package: readonly ["Ai.images.generate"];
|
|
538
|
+
};
|
|
539
|
+
readonly config: readonly [{
|
|
540
|
+
readonly name: "WORKBENCH_GATEWAY_KEY";
|
|
541
|
+
readonly required: true;
|
|
542
|
+
readonly secret: true;
|
|
543
|
+
readonly environments: readonly ["staging", "production"];
|
|
544
|
+
readonly description: "Project key with the images scope, delivered as a Worker secret by gw_key_issue";
|
|
545
|
+
}];
|
|
546
|
+
readonly allowed: {
|
|
547
|
+
readonly aliases: readonly [{
|
|
548
|
+
readonly alias: "image-default";
|
|
549
|
+
readonly provider: "google";
|
|
550
|
+
readonly default_model: "gemini-3.1-flash-image";
|
|
551
|
+
}, {
|
|
552
|
+
readonly alias: "image-pro";
|
|
553
|
+
readonly provider: "google";
|
|
554
|
+
readonly default_model: "gemini-3-pro-image";
|
|
555
|
+
}, {
|
|
556
|
+
readonly alias: "image-openai";
|
|
557
|
+
readonly provider: "openai";
|
|
558
|
+
readonly default_model: "gpt-image-2.5-sunburst";
|
|
559
|
+
}];
|
|
560
|
+
readonly aspect_ratios: readonly ["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"];
|
|
561
|
+
readonly reference_providers: readonly ["google"];
|
|
562
|
+
readonly reference_mime_types: readonly ["image/png", "image/jpeg", "image/webp"];
|
|
563
|
+
readonly output_mime_types: readonly ["image/png", "image/jpeg"];
|
|
564
|
+
readonly required_headers: readonly ["X-Workbench-Job"];
|
|
565
|
+
};
|
|
566
|
+
readonly limits: readonly [{
|
|
567
|
+
readonly id: "images.per-call";
|
|
568
|
+
readonly value: 1;
|
|
569
|
+
readonly unit: "images";
|
|
570
|
+
readonly per: "request";
|
|
571
|
+
readonly enforced_by: "gateway";
|
|
572
|
+
}, {
|
|
573
|
+
readonly id: "images.request-size";
|
|
574
|
+
readonly value: 20971520;
|
|
575
|
+
readonly unit: "bytes";
|
|
576
|
+
readonly per: "request";
|
|
577
|
+
readonly enforced_by: "gateway";
|
|
578
|
+
readonly refusal: "invalid_request";
|
|
579
|
+
}, {
|
|
580
|
+
readonly id: "images.upstream-timeout";
|
|
581
|
+
readonly value: 240;
|
|
582
|
+
readonly unit: "seconds";
|
|
583
|
+
readonly per: "request";
|
|
584
|
+
readonly enforced_by: "gateway";
|
|
585
|
+
readonly refusal: "upstream_timeout";
|
|
586
|
+
}];
|
|
587
|
+
readonly errors: readonly [{
|
|
588
|
+
readonly code: "model_not_allowed";
|
|
589
|
+
readonly http: 400;
|
|
590
|
+
readonly retryable: false;
|
|
591
|
+
readonly meaning: "Not an image alias";
|
|
592
|
+
}, {
|
|
593
|
+
readonly code: "invalid_request";
|
|
594
|
+
readonly http: 400;
|
|
595
|
+
readonly retryable: false;
|
|
596
|
+
readonly meaning: "A bad aspect ratio, prompt or reference, or a reference on an OpenAI model";
|
|
597
|
+
}, {
|
|
598
|
+
readonly code: "budget_exceeded";
|
|
599
|
+
readonly http: 402;
|
|
600
|
+
readonly retryable: false;
|
|
601
|
+
readonly meaning: "Enforced monthly budget reached";
|
|
602
|
+
}, {
|
|
603
|
+
readonly code: "upstream_error";
|
|
604
|
+
readonly http: 502;
|
|
605
|
+
readonly retryable: true;
|
|
606
|
+
readonly meaning: "The provider failed or returned no image after the Gateway's retries";
|
|
607
|
+
}, {
|
|
608
|
+
readonly code: "upstream_timeout";
|
|
609
|
+
readonly http: 504;
|
|
610
|
+
readonly retryable: true;
|
|
611
|
+
readonly meaning: "The provider didn't return an image within 4 minutes";
|
|
612
|
+
}];
|
|
613
|
+
readonly rules: readonly [{
|
|
614
|
+
readonly id: "images.aliases-only";
|
|
615
|
+
readonly kind: "must";
|
|
616
|
+
readonly text: "Ask for an image alias (image-default, image-pro or image-openai), never a provider model id.";
|
|
617
|
+
readonly enforced_by: "gateway";
|
|
618
|
+
readonly probe: "images.generate.image-default";
|
|
619
|
+
}, {
|
|
620
|
+
readonly id: "images.references-google-only";
|
|
621
|
+
readonly kind: "must_not";
|
|
622
|
+
readonly text: "Send reference images to an OpenAI alias. The Gateway refuses it with invalid_request rather than dropping them.";
|
|
623
|
+
readonly enforced_by: "gateway";
|
|
624
|
+
readonly probe: "images.generate.references-openai-refused";
|
|
625
|
+
}, {
|
|
626
|
+
readonly id: "images.no-silent-fallback";
|
|
627
|
+
readonly kind: "must_not";
|
|
628
|
+
readonly text: "Expect another provider to step in when one fails. The alias decides the provider; a failure is an error.";
|
|
629
|
+
readonly enforced_by: "gateway";
|
|
630
|
+
readonly probe: "images.generate.image-openai";
|
|
631
|
+
}, {
|
|
632
|
+
readonly id: "images.store-resolved-model";
|
|
633
|
+
readonly kind: "must";
|
|
634
|
+
readonly text: "Store the resolved model and request id with any image kept.";
|
|
635
|
+
readonly enforced_by: "review";
|
|
636
|
+
readonly probe: "images.generate.image-pro";
|
|
637
|
+
}];
|
|
638
|
+
readonly examples: readonly [{
|
|
639
|
+
readonly id: "images.example.generate";
|
|
640
|
+
readonly title: "Generate one image";
|
|
641
|
+
readonly lang: "ts";
|
|
642
|
+
readonly code: "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst img = await ai.images.generate({ prompt, aspectRatio: '3:2', job: 'article.hero' })\nawait env.IMAGES.put(key, img.bytes, { httpMetadata: { contentType: img.mimeType }, customMetadata: { model: img.model, requestId: img.requestId } })";
|
|
643
|
+
readonly probe: "images.generate.image-default";
|
|
644
|
+
}, {
|
|
645
|
+
readonly id: "images.example.reference";
|
|
646
|
+
readonly title: "Generate from a reference image (Google aliases only)";
|
|
647
|
+
readonly lang: "ts";
|
|
648
|
+
readonly code: "const img = await ai.images.generate({ prompt: 'The same scene at dusk', aspectRatio: '1:1', job: 'article.hero', model: 'image-default', references: [{ bytes, mimeType: 'image/png' }] })";
|
|
649
|
+
readonly probe: "images.generate.references-google";
|
|
650
|
+
}];
|
|
651
|
+
readonly probes: readonly [{
|
|
652
|
+
readonly id: "images.generate.image-default";
|
|
653
|
+
readonly half: "runtime";
|
|
654
|
+
readonly expect: "pass";
|
|
655
|
+
readonly smoke: true;
|
|
656
|
+
readonly cost_hint_usd: 0.067;
|
|
657
|
+
}, {
|
|
658
|
+
readonly id: "images.generate.image-pro";
|
|
659
|
+
readonly half: "runtime";
|
|
660
|
+
readonly expect: "pass";
|
|
661
|
+
readonly cost_hint_usd: 0.134;
|
|
662
|
+
}, {
|
|
663
|
+
readonly id: "images.generate.image-openai";
|
|
664
|
+
readonly half: "runtime";
|
|
665
|
+
readonly expect: "pass";
|
|
666
|
+
readonly cost_hint_usd: 0.011;
|
|
667
|
+
}, {
|
|
668
|
+
readonly id: "images.generate.references-google";
|
|
669
|
+
readonly half: "runtime";
|
|
670
|
+
readonly expect: "pass";
|
|
671
|
+
readonly cost_hint_usd: 0.07;
|
|
672
|
+
}, {
|
|
673
|
+
readonly id: "images.generate.references-openai-refused";
|
|
674
|
+
readonly half: "runtime";
|
|
675
|
+
readonly expect: "refused_as_expected";
|
|
676
|
+
readonly refusal: "invalid_request";
|
|
677
|
+
readonly cost_hint_usd: 0;
|
|
678
|
+
}];
|
|
679
|
+
};
|
|
401
680
|
};
|
|
402
681
|
export type Alias = (typeof capabilities)["ai"]["allowed"]["aliases"][number]["alias"];
|
|
403
682
|
export type GatewayScope = (typeof capabilities)["gateway"]["allowed"]["scopes"][number];
|
package/dist/capabilities.gen.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
|
|
2
2
|
// check:capabilities fails in Checks when this file is stale.
|
|
3
|
-
export const MANIFEST_VERSION = "
|
|
3
|
+
export const MANIFEST_VERSION = "491c578e91bc";
|
|
4
4
|
export const capabilities = {
|
|
5
5
|
"ai": {
|
|
6
6
|
"$schema": "./schema.json",
|
|
@@ -303,7 +303,7 @@ export const capabilities = {
|
|
|
303
303
|
"component": "gateway",
|
|
304
304
|
"title": "Workbench Gateway: keys, headers, budgets and errors",
|
|
305
305
|
"summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
|
|
306
|
-
"status": "
|
|
306
|
+
"status": "built",
|
|
307
307
|
"surfaces": {
|
|
308
308
|
"gateway": [
|
|
309
309
|
"GET /v1/health",
|
|
@@ -386,6 +386,12 @@ export const capabilities = {
|
|
|
386
386
|
"name": "Idempotency-Key",
|
|
387
387
|
"required": false,
|
|
388
388
|
"description": "Email only: a repeat within 24 hours returns the stored result"
|
|
389
|
+
},
|
|
390
|
+
{
|
|
391
|
+
"name": "X-Workbench-Env",
|
|
392
|
+
"required": false,
|
|
393
|
+
"pattern": "^(development|staging|production)$",
|
|
394
|
+
"description": "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised"
|
|
389
395
|
}
|
|
390
396
|
],
|
|
391
397
|
"response_headers": [
|
|
@@ -414,6 +420,14 @@ export const capabilities = {
|
|
|
414
420
|
"per": "isolate",
|
|
415
421
|
"enforced_by": "gateway"
|
|
416
422
|
},
|
|
423
|
+
{
|
|
424
|
+
"id": "gateway.rate-limit",
|
|
425
|
+
"value": 300,
|
|
426
|
+
"unit": "requests",
|
|
427
|
+
"per": "minute per key",
|
|
428
|
+
"enforced_by": "gateway",
|
|
429
|
+
"refusal": "rate_limited"
|
|
430
|
+
},
|
|
417
431
|
{
|
|
418
432
|
"id": "gateway.job-format",
|
|
419
433
|
"value": "[a-z0-9._-]{1,64}",
|
|
@@ -471,6 +485,18 @@ export const capabilities = {
|
|
|
471
485
|
"http": 504,
|
|
472
486
|
"retryable": true,
|
|
473
487
|
"meaning": "The vendor didn't answer in time"
|
|
488
|
+
},
|
|
489
|
+
{
|
|
490
|
+
"code": "not_found",
|
|
491
|
+
"http": 404,
|
|
492
|
+
"retryable": false,
|
|
493
|
+
"meaning": "No such path. Every documented endpoint checks the key and scope first, even one not built yet"
|
|
494
|
+
},
|
|
495
|
+
{
|
|
496
|
+
"code": "internal_error",
|
|
497
|
+
"http": 500,
|
|
498
|
+
"retryable": true,
|
|
499
|
+
"meaning": "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor"
|
|
474
500
|
}
|
|
475
501
|
],
|
|
476
502
|
"rules": [
|
|
@@ -488,6 +514,13 @@ export const capabilities = {
|
|
|
488
514
|
"enforced_by": "gateway",
|
|
489
515
|
"probe": "gateway.wrong-environment"
|
|
490
516
|
},
|
|
517
|
+
{
|
|
518
|
+
"id": "gateway.timing-headers",
|
|
519
|
+
"kind": "must",
|
|
520
|
+
"text": "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.",
|
|
521
|
+
"enforced_by": "gateway",
|
|
522
|
+
"probe": "gateway.server-timing"
|
|
523
|
+
},
|
|
491
524
|
{
|
|
492
525
|
"id": "gateway.request-id-kept",
|
|
493
526
|
"kind": "must",
|
|
@@ -504,6 +537,13 @@ export const capabilities = {
|
|
|
504
537
|
"smoke": true,
|
|
505
538
|
"cost_hint_usd": 0
|
|
506
539
|
},
|
|
540
|
+
{
|
|
541
|
+
"id": "gateway.server-timing",
|
|
542
|
+
"half": "runtime",
|
|
543
|
+
"expect": "pass",
|
|
544
|
+
"smoke": true,
|
|
545
|
+
"cost_hint_usd": 0
|
|
546
|
+
},
|
|
507
547
|
{
|
|
508
548
|
"id": "gateway.bad-key",
|
|
509
549
|
"half": "runtime",
|
|
@@ -550,5 +590,343 @@ export const capabilities = {
|
|
|
550
590
|
"note": "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets"
|
|
551
591
|
}
|
|
552
592
|
]
|
|
593
|
+
},
|
|
594
|
+
"image-search": {
|
|
595
|
+
"$schema": "./schema.json",
|
|
596
|
+
"format": 1,
|
|
597
|
+
"component": "image-search",
|
|
598
|
+
"title": "Image search through the Gateway",
|
|
599
|
+
"summary": "Web image search through Serper, normalised to one result shape and metered against the project's budget. Apps never hold a Serper key.",
|
|
600
|
+
"status": "planned",
|
|
601
|
+
"surfaces": {
|
|
602
|
+
"gateway": [
|
|
603
|
+
"POST /v1/images/search"
|
|
604
|
+
],
|
|
605
|
+
"package": [
|
|
606
|
+
"Ai.images.search"
|
|
607
|
+
]
|
|
608
|
+
},
|
|
609
|
+
"config": [
|
|
610
|
+
{
|
|
611
|
+
"name": "WORKBENCH_GATEWAY_KEY",
|
|
612
|
+
"required": true,
|
|
613
|
+
"secret": true,
|
|
614
|
+
"environments": [
|
|
615
|
+
"staging",
|
|
616
|
+
"production"
|
|
617
|
+
],
|
|
618
|
+
"description": "Project key with the search scope, delivered as a Worker secret by gw_key_issue"
|
|
619
|
+
}
|
|
620
|
+
],
|
|
621
|
+
"allowed": {
|
|
622
|
+
"providers": [
|
|
623
|
+
"serper"
|
|
624
|
+
],
|
|
625
|
+
"result_fields": [
|
|
626
|
+
"title",
|
|
627
|
+
"image_url",
|
|
628
|
+
"thumbnail_url",
|
|
629
|
+
"width",
|
|
630
|
+
"height",
|
|
631
|
+
"source",
|
|
632
|
+
"page_url"
|
|
633
|
+
],
|
|
634
|
+
"required_headers": [
|
|
635
|
+
"X-Workbench-Job"
|
|
636
|
+
]
|
|
637
|
+
},
|
|
638
|
+
"limits": [
|
|
639
|
+
{
|
|
640
|
+
"id": "image-search.num",
|
|
641
|
+
"value": "1-100",
|
|
642
|
+
"unit": "results",
|
|
643
|
+
"per": "request",
|
|
644
|
+
"enforced_by": "gateway",
|
|
645
|
+
"refusal": "invalid_request"
|
|
646
|
+
},
|
|
647
|
+
{
|
|
648
|
+
"id": "image-search.num-default",
|
|
649
|
+
"value": 10,
|
|
650
|
+
"unit": "results",
|
|
651
|
+
"per": "request",
|
|
652
|
+
"enforced_by": "gateway"
|
|
653
|
+
},
|
|
654
|
+
{
|
|
655
|
+
"id": "image-search.upstream-timeout",
|
|
656
|
+
"value": 90,
|
|
657
|
+
"unit": "seconds",
|
|
658
|
+
"per": "request",
|
|
659
|
+
"enforced_by": "gateway",
|
|
660
|
+
"refusal": "upstream_timeout"
|
|
661
|
+
}
|
|
662
|
+
],
|
|
663
|
+
"errors": [
|
|
664
|
+
{
|
|
665
|
+
"code": "invalid_request",
|
|
666
|
+
"http": 400,
|
|
667
|
+
"retryable": false,
|
|
668
|
+
"meaning": "An empty query or a bad num, gl or hl"
|
|
669
|
+
},
|
|
670
|
+
{
|
|
671
|
+
"code": "budget_exceeded",
|
|
672
|
+
"http": 402,
|
|
673
|
+
"retryable": false,
|
|
674
|
+
"meaning": "Enforced monthly budget reached"
|
|
675
|
+
},
|
|
676
|
+
{
|
|
677
|
+
"code": "upstream_error",
|
|
678
|
+
"http": 502,
|
|
679
|
+
"retryable": true,
|
|
680
|
+
"meaning": "Serper failed after the Gateway's retries"
|
|
681
|
+
},
|
|
682
|
+
{
|
|
683
|
+
"code": "upstream_timeout",
|
|
684
|
+
"http": 504,
|
|
685
|
+
"retryable": true,
|
|
686
|
+
"meaning": "Serper didn't answer within 90 seconds"
|
|
687
|
+
}
|
|
688
|
+
],
|
|
689
|
+
"rules": [
|
|
690
|
+
{
|
|
691
|
+
"id": "image-search.https-only",
|
|
692
|
+
"kind": "must",
|
|
693
|
+
"text": "Use only https image and page URLs from the results; the Gateway drops any result without one.",
|
|
694
|
+
"enforced_by": "gateway",
|
|
695
|
+
"probe": "image-search.serper"
|
|
696
|
+
},
|
|
697
|
+
{
|
|
698
|
+
"id": "image-search.licence-check",
|
|
699
|
+
"kind": "must",
|
|
700
|
+
"text": "Treat results as leads, not as images the app may republish. Check the source's licence before storing or showing one.",
|
|
701
|
+
"enforced_by": "review",
|
|
702
|
+
"probe": "image-search.serper"
|
|
703
|
+
}
|
|
704
|
+
],
|
|
705
|
+
"examples": [
|
|
706
|
+
{
|
|
707
|
+
"id": "image-search.example.search",
|
|
708
|
+
"title": "Search for images",
|
|
709
|
+
"lang": "ts",
|
|
710
|
+
"code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst results = await ai.images.search({ q: 'Mayon volcano', job: 'editor.image-search', num: 10 })",
|
|
711
|
+
"probe": "image-search.serper"
|
|
712
|
+
}
|
|
713
|
+
],
|
|
714
|
+
"probes": [
|
|
715
|
+
{
|
|
716
|
+
"id": "image-search.serper",
|
|
717
|
+
"half": "runtime",
|
|
718
|
+
"expect": "pass",
|
|
719
|
+
"smoke": true,
|
|
720
|
+
"cost_hint_usd": 0.001
|
|
721
|
+
}
|
|
722
|
+
]
|
|
723
|
+
},
|
|
724
|
+
"images": {
|
|
725
|
+
"$schema": "./schema.json",
|
|
726
|
+
"format": 1,
|
|
727
|
+
"component": "images",
|
|
728
|
+
"title": "Image generation through the Gateway",
|
|
729
|
+
"summary": "One image per call from Gemini or OpenAI, chosen by a Workbench alias and metered against the project's budget. Apps never hold a Google or OpenAI key, and the Gateway never falls back to another provider.",
|
|
730
|
+
"status": "planned",
|
|
731
|
+
"surfaces": {
|
|
732
|
+
"gateway": [
|
|
733
|
+
"POST /v1/images/generate"
|
|
734
|
+
],
|
|
735
|
+
"package": [
|
|
736
|
+
"Ai.images.generate"
|
|
737
|
+
]
|
|
738
|
+
},
|
|
739
|
+
"config": [
|
|
740
|
+
{
|
|
741
|
+
"name": "WORKBENCH_GATEWAY_KEY",
|
|
742
|
+
"required": true,
|
|
743
|
+
"secret": true,
|
|
744
|
+
"environments": [
|
|
745
|
+
"staging",
|
|
746
|
+
"production"
|
|
747
|
+
],
|
|
748
|
+
"description": "Project key with the images scope, delivered as a Worker secret by gw_key_issue"
|
|
749
|
+
}
|
|
750
|
+
],
|
|
751
|
+
"allowed": {
|
|
752
|
+
"aliases": [
|
|
753
|
+
{
|
|
754
|
+
"alias": "image-default",
|
|
755
|
+
"provider": "google",
|
|
756
|
+
"default_model": "gemini-3.1-flash-image"
|
|
757
|
+
},
|
|
758
|
+
{
|
|
759
|
+
"alias": "image-pro",
|
|
760
|
+
"provider": "google",
|
|
761
|
+
"default_model": "gemini-3-pro-image"
|
|
762
|
+
},
|
|
763
|
+
{
|
|
764
|
+
"alias": "image-openai",
|
|
765
|
+
"provider": "openai",
|
|
766
|
+
"default_model": "gpt-image-2.5-sunburst"
|
|
767
|
+
}
|
|
768
|
+
],
|
|
769
|
+
"aspect_ratios": [
|
|
770
|
+
"1:1",
|
|
771
|
+
"3:2",
|
|
772
|
+
"2:3",
|
|
773
|
+
"4:3",
|
|
774
|
+
"3:4",
|
|
775
|
+
"16:9",
|
|
776
|
+
"9:16"
|
|
777
|
+
],
|
|
778
|
+
"reference_providers": [
|
|
779
|
+
"google"
|
|
780
|
+
],
|
|
781
|
+
"reference_mime_types": [
|
|
782
|
+
"image/png",
|
|
783
|
+
"image/jpeg",
|
|
784
|
+
"image/webp"
|
|
785
|
+
],
|
|
786
|
+
"output_mime_types": [
|
|
787
|
+
"image/png",
|
|
788
|
+
"image/jpeg"
|
|
789
|
+
],
|
|
790
|
+
"required_headers": [
|
|
791
|
+
"X-Workbench-Job"
|
|
792
|
+
]
|
|
793
|
+
},
|
|
794
|
+
"limits": [
|
|
795
|
+
{
|
|
796
|
+
"id": "images.per-call",
|
|
797
|
+
"value": 1,
|
|
798
|
+
"unit": "images",
|
|
799
|
+
"per": "request",
|
|
800
|
+
"enforced_by": "gateway"
|
|
801
|
+
},
|
|
802
|
+
{
|
|
803
|
+
"id": "images.request-size",
|
|
804
|
+
"value": 20971520,
|
|
805
|
+
"unit": "bytes",
|
|
806
|
+
"per": "request",
|
|
807
|
+
"enforced_by": "gateway",
|
|
808
|
+
"refusal": "invalid_request"
|
|
809
|
+
},
|
|
810
|
+
{
|
|
811
|
+
"id": "images.upstream-timeout",
|
|
812
|
+
"value": 240,
|
|
813
|
+
"unit": "seconds",
|
|
814
|
+
"per": "request",
|
|
815
|
+
"enforced_by": "gateway",
|
|
816
|
+
"refusal": "upstream_timeout"
|
|
817
|
+
}
|
|
818
|
+
],
|
|
819
|
+
"errors": [
|
|
820
|
+
{
|
|
821
|
+
"code": "model_not_allowed",
|
|
822
|
+
"http": 400,
|
|
823
|
+
"retryable": false,
|
|
824
|
+
"meaning": "Not an image alias"
|
|
825
|
+
},
|
|
826
|
+
{
|
|
827
|
+
"code": "invalid_request",
|
|
828
|
+
"http": 400,
|
|
829
|
+
"retryable": false,
|
|
830
|
+
"meaning": "A bad aspect ratio, prompt or reference, or a reference on an OpenAI model"
|
|
831
|
+
},
|
|
832
|
+
{
|
|
833
|
+
"code": "budget_exceeded",
|
|
834
|
+
"http": 402,
|
|
835
|
+
"retryable": false,
|
|
836
|
+
"meaning": "Enforced monthly budget reached"
|
|
837
|
+
},
|
|
838
|
+
{
|
|
839
|
+
"code": "upstream_error",
|
|
840
|
+
"http": 502,
|
|
841
|
+
"retryable": true,
|
|
842
|
+
"meaning": "The provider failed or returned no image after the Gateway's retries"
|
|
843
|
+
},
|
|
844
|
+
{
|
|
845
|
+
"code": "upstream_timeout",
|
|
846
|
+
"http": 504,
|
|
847
|
+
"retryable": true,
|
|
848
|
+
"meaning": "The provider didn't return an image within 4 minutes"
|
|
849
|
+
}
|
|
850
|
+
],
|
|
851
|
+
"rules": [
|
|
852
|
+
{
|
|
853
|
+
"id": "images.aliases-only",
|
|
854
|
+
"kind": "must",
|
|
855
|
+
"text": "Ask for an image alias (image-default, image-pro or image-openai), never a provider model id.",
|
|
856
|
+
"enforced_by": "gateway",
|
|
857
|
+
"probe": "images.generate.image-default"
|
|
858
|
+
},
|
|
859
|
+
{
|
|
860
|
+
"id": "images.references-google-only",
|
|
861
|
+
"kind": "must_not",
|
|
862
|
+
"text": "Send reference images to an OpenAI alias. The Gateway refuses it with invalid_request rather than dropping them.",
|
|
863
|
+
"enforced_by": "gateway",
|
|
864
|
+
"probe": "images.generate.references-openai-refused"
|
|
865
|
+
},
|
|
866
|
+
{
|
|
867
|
+
"id": "images.no-silent-fallback",
|
|
868
|
+
"kind": "must_not",
|
|
869
|
+
"text": "Expect another provider to step in when one fails. The alias decides the provider; a failure is an error.",
|
|
870
|
+
"enforced_by": "gateway",
|
|
871
|
+
"probe": "images.generate.image-openai"
|
|
872
|
+
},
|
|
873
|
+
{
|
|
874
|
+
"id": "images.store-resolved-model",
|
|
875
|
+
"kind": "must",
|
|
876
|
+
"text": "Store the resolved model and request id with any image kept.",
|
|
877
|
+
"enforced_by": "review",
|
|
878
|
+
"probe": "images.generate.image-pro"
|
|
879
|
+
}
|
|
880
|
+
],
|
|
881
|
+
"examples": [
|
|
882
|
+
{
|
|
883
|
+
"id": "images.example.generate",
|
|
884
|
+
"title": "Generate one image",
|
|
885
|
+
"lang": "ts",
|
|
886
|
+
"code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst img = await ai.images.generate({ prompt, aspectRatio: '3:2', job: 'article.hero' })\nawait env.IMAGES.put(key, img.bytes, { httpMetadata: { contentType: img.mimeType }, customMetadata: { model: img.model, requestId: img.requestId } })",
|
|
887
|
+
"probe": "images.generate.image-default"
|
|
888
|
+
},
|
|
889
|
+
{
|
|
890
|
+
"id": "images.example.reference",
|
|
891
|
+
"title": "Generate from a reference image (Google aliases only)",
|
|
892
|
+
"lang": "ts",
|
|
893
|
+
"code": "const img = await ai.images.generate({ prompt: 'The same scene at dusk', aspectRatio: '1:1', job: 'article.hero', model: 'image-default', references: [{ bytes, mimeType: 'image/png' }] })",
|
|
894
|
+
"probe": "images.generate.references-google"
|
|
895
|
+
}
|
|
896
|
+
],
|
|
897
|
+
"probes": [
|
|
898
|
+
{
|
|
899
|
+
"id": "images.generate.image-default",
|
|
900
|
+
"half": "runtime",
|
|
901
|
+
"expect": "pass",
|
|
902
|
+
"smoke": true,
|
|
903
|
+
"cost_hint_usd": 0.067
|
|
904
|
+
},
|
|
905
|
+
{
|
|
906
|
+
"id": "images.generate.image-pro",
|
|
907
|
+
"half": "runtime",
|
|
908
|
+
"expect": "pass",
|
|
909
|
+
"cost_hint_usd": 0.134
|
|
910
|
+
},
|
|
911
|
+
{
|
|
912
|
+
"id": "images.generate.image-openai",
|
|
913
|
+
"half": "runtime",
|
|
914
|
+
"expect": "pass",
|
|
915
|
+
"cost_hint_usd": 0.011
|
|
916
|
+
},
|
|
917
|
+
{
|
|
918
|
+
"id": "images.generate.references-google",
|
|
919
|
+
"half": "runtime",
|
|
920
|
+
"expect": "pass",
|
|
921
|
+
"cost_hint_usd": 0.07
|
|
922
|
+
},
|
|
923
|
+
{
|
|
924
|
+
"id": "images.generate.references-openai-refused",
|
|
925
|
+
"half": "runtime",
|
|
926
|
+
"expect": "refused_as_expected",
|
|
927
|
+
"refusal": "invalid_request",
|
|
928
|
+
"cost_hint_usd": 0
|
|
929
|
+
}
|
|
930
|
+
]
|
|
553
931
|
}
|
|
554
932
|
};
|
|
@@ -40,6 +40,31 @@ export declare const allowedSchemas: {
|
|
|
40
40
|
server_tools: z.ZodArray<z.ZodString>;
|
|
41
41
|
required_headers: z.ZodArray<z.ZodString>;
|
|
42
42
|
}, z.core.$strict>;
|
|
43
|
+
images: z.ZodObject<{
|
|
44
|
+
aliases: z.ZodArray<z.ZodObject<{
|
|
45
|
+
alias: z.ZodString;
|
|
46
|
+
default_model: z.ZodString;
|
|
47
|
+
provider: z.ZodEnum<{
|
|
48
|
+
google: "google";
|
|
49
|
+
openai: "openai";
|
|
50
|
+
}>;
|
|
51
|
+
}, z.core.$strict>>;
|
|
52
|
+
aspect_ratios: z.ZodArray<z.ZodString>;
|
|
53
|
+
reference_providers: z.ZodArray<z.ZodEnum<{
|
|
54
|
+
google: "google";
|
|
55
|
+
openai: "openai";
|
|
56
|
+
}>>;
|
|
57
|
+
reference_mime_types: z.ZodArray<z.ZodString>;
|
|
58
|
+
output_mime_types: z.ZodArray<z.ZodString>;
|
|
59
|
+
required_headers: z.ZodArray<z.ZodString>;
|
|
60
|
+
}, z.core.$strict>;
|
|
61
|
+
"image-search": z.ZodObject<{
|
|
62
|
+
providers: z.ZodArray<z.ZodEnum<{
|
|
63
|
+
serper: "serper";
|
|
64
|
+
}>>;
|
|
65
|
+
result_fields: z.ZodArray<z.ZodString>;
|
|
66
|
+
required_headers: z.ZodArray<z.ZodString>;
|
|
67
|
+
}, z.core.$strict>;
|
|
43
68
|
config: z.ZodObject<{
|
|
44
69
|
environments: z.ZodArray<z.ZodEnum<{
|
|
45
70
|
development: "development";
|
|
@@ -100,6 +100,19 @@ export const allowedSchemas = {
|
|
|
100
100
|
server_tools: z.array(z.string().min(1)),
|
|
101
101
|
required_headers: z.array(z.string().min(1)),
|
|
102
102
|
}),
|
|
103
|
+
images: z.strictObject({
|
|
104
|
+
aliases: z.array(aliasEntry.extend({ provider: z.enum(["google", "openai"]) })).min(1),
|
|
105
|
+
aspect_ratios: z.array(z.string().regex(/^[1-9][0-9]?:[1-9][0-9]?$/, "w:h")).min(1),
|
|
106
|
+
reference_providers: z.array(z.enum(["google", "openai"])),
|
|
107
|
+
reference_mime_types: z.array(z.string().regex(/^image\/[a-z0-9.+-]+$/)).min(1),
|
|
108
|
+
output_mime_types: z.array(z.string().regex(/^image\/[a-z0-9.+-]+$/)).min(1),
|
|
109
|
+
required_headers: z.array(z.string().min(1)),
|
|
110
|
+
}),
|
|
111
|
+
"image-search": z.strictObject({
|
|
112
|
+
providers: z.array(z.enum(["serper"])).min(1),
|
|
113
|
+
result_fields: z.array(z.string().regex(/^[a-z][a-z0-9_]*$/)).min(1),
|
|
114
|
+
required_headers: z.array(z.string().min(1)),
|
|
115
|
+
}),
|
|
103
116
|
config: z.strictObject({
|
|
104
117
|
environments: z.array(envName).min(1),
|
|
105
118
|
}),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mccaskie-labs/workbench-config",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"type": "module",
|