open-api-manual.html
27.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
<title>Agent Invocation API</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,400..800&family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
<style>
:root {
--paper: #f6f7f2;
--paper-raised: #ffffff;
--ink: #1c211d;
--ink-soft: #4d564e;
--ink-faint: #7c8579;
--line: #dce0d5;
--line-soft: #e8ebe2;
--accent: #7c8f1f;
--accent-ink: #fdfff2;
--accent-soft: #eef1de;
--code-bg: #1f241f;
--code-ink: #e7ead9;
--code-line: #343a30;
--status-queued: #5b7590;
--status-queued-bg: #e9eef3;
--status-running: #b8811f;
--status-running-bg: #f7edd9;
--status-completed: #3f8f5f;
--status-completed-bg: #e3f1e7;
--status-failed: #b4453a;
--status-failed-bg: #f7e4e1;
--shadow: 0 1px 2px rgba(28,33,29,0.04), 0 8px 24px -12px rgba(28,33,29,0.12);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--paper: #14170f;
--paper-raised: #1b1f16;
--ink: #eef0e6;
--ink-soft: #b7bfae;
--ink-faint: #808875;
--line: #333a2b;
--line-soft: #262b1f;
--accent: #b8cf3f;
--accent-ink: #14170f;
--accent-soft: #232a17;
--code-bg: #0e100c;
--code-ink: #dfe3d3;
--code-line: #2a2f24;
--status-queued: #8fb0d6;
--status-queued-bg: #1c2733;
--status-running: #e0b25a;
--status-running-bg: #332a17;
--status-completed: #7fcb9c;
--status-completed-bg: #17301f;
--status-failed: #e0847a;
--status-failed-bg: #331d1a;
--shadow: 0 1px 2px rgba(0,0,0,0.3), 0 12px 32px -16px rgba(0,0,0,0.6);
}
}
:root[data-theme="dark"] {
--paper: #14170f;
--paper-raised: #1b1f16;
--ink: #eef0e6;
--ink-soft: #b7bfae;
--ink-faint: #808875;
--line: #333a2b;
--line-soft: #262b1f;
--accent: #b8cf3f;
--accent-ink: #14170f;
--accent-soft: #232a17;
--code-bg: #0e100c;
--code-ink: #dfe3d3;
--code-line: #2a2f24;
--status-queued: #8fb0d6;
--status-queued-bg: #1c2733;
--status-running: #e0b25a;
--status-running-bg: #332a17;
--status-completed: #7fcb9c;
--status-completed-bg: #17301f;
--status-failed: #e0847a;
--status-failed-bg: #331d1a;
--shadow: 0 1px 2px rgba(0,0,0,0.3), 0 12px 32px -16px rgba(0,0,0,0.6);
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }
body {
margin: 0;
background: var(--paper);
color: var(--ink);
font-family: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, sans-serif;
font-size: 16px;
line-height: 1.6;
-webkit-font-smoothing: antialiased;
}
code, .mono, .badge, .endpoint, .tabular { font-family: 'IBM Plex Mono', ui-monospace, monospace; font-variant-numeric: tabular-nums; }
h1, h2, h3 { font-family: 'Bricolage Grotesque', 'IBM Plex Sans', sans-serif; text-wrap: balance; color: var(--ink); letter-spacing: -0.01em; }
a { color: var(--accent); }
a:focus-visible, button:focus-visible, summary:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
.shell { display: grid; grid-template-columns: 236px minmax(0, 1fr); gap: 0; max-width: 1180px; margin: 0 auto; }
/* ── Sidebar ── */
nav.toc {
position: sticky; top: 0; align-self: start; height: 100vh; overflow-y: auto;
padding: 40px 20px 40px 32px; border-right: 1px solid var(--line-soft);
}
.brand { display: flex; align-items: center; gap: 9px; margin-bottom: 30px; }
.brand-mark { width: 26px; height: 26px; border-radius: 7px; background: var(--accent); display: flex; align-items: center; justify-content: center; font-size: 14px; flex: none; }
.brand-text { font-family: 'Bricolage Grotesque', sans-serif; font-weight: 700; font-size: 15px; letter-spacing: -0.01em; }
.brand-sub { font-size: 11px; color: var(--ink-faint); letter-spacing: 0.04em; text-transform: uppercase; margin-top: 1px; }
nav.toc ol { list-style: none; margin: 0; padding: 0; counter-reset: toc; }
nav.toc li { counter-increment: toc; margin: 0; }
nav.toc a {
display: flex; gap: 9px; align-items: baseline; padding: 6px 8px; margin: 0 -8px; border-radius: 6px;
color: var(--ink-soft); text-decoration: none; font-size: 13.5px; transition: background 0.12s, color 0.12s;
}
nav.toc a:hover { background: var(--line-soft); color: var(--ink); }
nav.toc a::before { content: counter(toc, decimal-leading-zero); font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: var(--ink-faint); flex: none; }
.toc-foot { margin-top: 28px; padding-top: 18px; border-top: 1px solid var(--line-soft); font-size: 12px; color: var(--ink-faint); }
.toc-foot .base-url { display: block; margin-top: 6px; font-family: 'IBM Plex Mono', monospace; font-size: 11.5px; color: var(--ink-soft); word-break: break-all; }
/* ── Main ── */
main { padding: 56px 48px 120px; min-width: 0; }
.eyebrow { font-family: 'IBM Plex Mono', monospace; font-size: 12px; letter-spacing: 0.09em; text-transform: uppercase; color: var(--accent); margin: 0 0 14px; }
h1.title { font-size: clamp(30px, 4vw, 40px); margin: 0 0 14px; line-height: 1.08; }
.lede { font-size: 17px; color: var(--ink-soft); max-width: 62ch; margin: 0 0 40px; }
/* pipeline diagram */
.pipeline { display: flex; align-items: stretch; gap: 0; margin: 0 0 56px; border: 1px solid var(--line); border-radius: 12px; overflow: hidden; background: var(--paper-raised); box-shadow: var(--shadow); }
.pipe-step { flex: 1; padding: 18px 16px; position: relative; min-width: 0; }
.pipe-step + .pipe-step { border-left: 1px solid var(--line); }
.pipe-label { font-family: 'IBM Plex Mono', monospace; font-size: 10.5px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--ink-faint); margin-bottom: 6px; }
.pipe-verb { font-size: 14px; font-weight: 600; }
.pipe-step[data-state="request"] .pipe-verb { color: var(--ink); }
.pipe-step[data-state="queued"] { background: var(--status-queued-bg); }
.pipe-step[data-state="queued"] .pipe-verb { color: var(--status-queued); }
.pipe-step[data-state="running"] { background: var(--status-running-bg); }
.pipe-step[data-state="running"] .pipe-verb { color: var(--status-running); }
.pipe-step[data-state="completed"] { background: var(--status-completed-bg); }
.pipe-step[data-state="completed"] .pipe-verb { color: var(--status-completed); }
section { margin: 0 0 64px; scroll-margin-top: 24px; }
section h2 { font-size: 23px; margin: 0 0 6px; display: flex; align-items: center; gap: 10px; }
.h2-num { font-family: 'IBM Plex Mono', monospace; font-size: 14px; color: var(--accent); font-weight: 500; }
.section-dek { color: var(--ink-soft); max-width: 66ch; margin: 0 0 26px; font-size: 15px; }
h3 { font-size: 16.5px; margin: 30px 0 10px; font-weight: 600; }
p { max-width: 68ch; }
ul, ol { max-width: 68ch; padding-left: 22px; }
li { margin: 4px 0; }
/* endpoint card */
.endpoint-card { border: 1px solid var(--line); border-radius: 10px; background: var(--paper-raised); box-shadow: var(--shadow); margin: 18px 0 22px; overflow: hidden; }
.endpoint-head { display: flex; align-items: center; gap: 10px; padding: 14px 18px; border-bottom: 1px solid var(--line-soft); flex-wrap: wrap; }
.verb { font-family: 'IBM Plex Mono', monospace; font-size: 12px; font-weight: 600; padding: 3px 8px; border-radius: 5px; background: var(--accent); color: var(--accent-ink); letter-spacing: 0.03em; }
.verb.get { background: var(--status-queued); color: var(--accent-ink); }
.endpoint { font-size: 13.5px; color: var(--ink); overflow-x: auto; white-space: nowrap; }
.endpoint-body { padding: 16px 18px 18px; }
.endpoint-note { font-size: 13.5px; color: var(--ink-soft); margin: 0 0 12px; }
/* two-up compare */
.compare { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; margin: 18px 0 26px; }
@media (max-width: 720px) { .compare { grid-template-columns: 1fr; } }
.compare-card { border: 1px solid var(--line); border-radius: 10px; padding: 16px 18px; background: var(--paper-raised); }
.compare-card h4 { margin: 0 0 4px; font-size: 14px; font-family: 'IBM Plex Mono', monospace; color: var(--accent); }
.compare-card p { margin: 0; font-size: 13.5px; color: var(--ink-soft); }
.compare-card .who { font-size: 12.5px; color: var(--ink-faint); margin-top: 8px; }
table { width: 100%; border-collapse: collapse; font-size: 13.5px; margin: 6px 0 20px; }
.table-wrap { overflow-x: auto; }
th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--line-soft); vertical-align: top; }
th { font-family: 'IBM Plex Mono', monospace; font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--ink-faint); font-weight: 500; }
td code { font-size: 12.5px; background: var(--accent-soft); padding: 1px 5px; border-radius: 4px; }
.req { color: var(--accent); font-weight: 600; font-size: 12px; }
.opt { color: var(--ink-faint); font-size: 12px; }
/* code blocks */
.code-block { position: relative; background: var(--code-bg); color: var(--code-ink); border-radius: 10px; margin: 0 0 20px; box-shadow: var(--shadow); }
.code-block .code-label { display: flex; justify-content: space-between; align-items: center; padding: 10px 16px; border-bottom: 1px solid var(--code-line); font-family: 'IBM Plex Mono', monospace; font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: #9fa693; }
.code-block pre { margin: 0; padding: 16px 18px 18px; overflow-x: auto; font-size: 13px; line-height: 1.6; }
.copy-btn { font-family: 'IBM Plex Sans', sans-serif; font-size: 11.5px; background: transparent; border: 1px solid var(--code-line); color: #9fa693; padding: 3px 9px; border-radius: 5px; cursor: pointer; transition: border-color 0.15s, color 0.15s; }
.copy-btn:hover { border-color: var(--accent); color: var(--accent); }
.copy-btn.copied { border-color: var(--status-completed); color: var(--status-completed); }
.tok-key { color: #8fd6c9; }
.tok-str { color: #d7c98a; }
.tok-num { color: #e0a26f; }
.tok-bool { color: #b8a0e0; }
.tok-comment { color: #6f7965; font-style: italic; }
.tok-verb { color: #9fc773; }
/* status badges */
.badge { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; font-weight: 500; padding: 3px 10px; border-radius: 100px; }
.badge::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
.badge.queued { background: var(--status-queued-bg); color: var(--status-queued); }
.badge.running { background: var(--status-running-bg); color: var(--status-running); }
.badge.completed { background: var(--status-completed-bg); color: var(--status-completed); }
.badge.failed { background: var(--status-failed-bg); color: var(--status-failed); }
.status-grid { display: grid; grid-template-columns: auto 1fr; gap: 10px 18px; margin: 18px 0 26px; align-items: baseline; }
.status-grid dt { grid-column: 1; }
.status-grid dd { grid-column: 2; margin: 0; color: var(--ink-soft); font-size: 14px; max-width: 56ch; }
.callout { border: 1px solid var(--line); border-left: 3px solid var(--accent); background: var(--accent-soft); border-radius: 0 8px 8px 0; padding: 14px 18px; margin: 20px 0; font-size: 14px; color: var(--ink); max-width: 68ch; }
.callout strong { color: var(--ink); }
.worked-example { border: 1px solid var(--line); border-radius: 12px; background: var(--paper-raised); box-shadow: var(--shadow); padding: 24px 26px 28px; }
.we-step { display: flex; gap: 16px; padding: 16px 0; }
.we-step + .we-step { border-top: 1px solid var(--line-soft); }
.we-num { font-family: 'IBM Plex Mono', monospace; font-size: 12px; color: var(--accent); font-weight: 600; width: 20px; flex: none; padding-top: 2px; }
.we-body { min-width: 0; flex: 1; }
.we-body h4 { margin: 0 0 6px; font-size: 14.5px; }
.we-body .code-block { margin: 10px 0 0; }
footer.page-foot { border-top: 1px solid var(--line-soft); margin-top: 40px; padding-top: 22px; font-size: 13px; color: var(--ink-faint); }
::selection { background: var(--accent); color: var(--accent-ink); }
@media (max-width: 860px) {
.shell { grid-template-columns: 1fr; }
nav.toc { position: static; height: auto; border-right: none; border-bottom: 1px solid var(--line-soft); padding: 24px 24px 20px; }
main { padding: 36px 22px 90px; }
}
</style>
<div class="shell">
<nav class="toc" aria-label="目录">
<div class="brand">
<span class="brand-mark" aria-hidden="true">🍋</span>
<div>
<div class="brand-text">LemonBoss</div>
<div class="brand-sub">Open API</div>
</div>
</div>
<ol>
<li><a href="#overview">总览</a></li>
<li><a href="#auth">身份验证</a></li>
<li><a href="#endpoints">两种调用形态</a></li>
<li><a href="#invoke">发起调用</a></li>
<li><a href="#poll">轮询结果</a></li>
<li><a href="#status">任务状态参考</a></li>
<li><a href="#memory">携带上下文</a></li>
<li><a href="#example">完整示例</a></li>
<li><a href="#errors">错误参考</a></li>
</ol>
<div class="toc-foot">
Base URL
<span class="base-url">https://lemonboss.wudaima.com/api/open</span>
</div>
</nav>
<main>
<section id="overview">
<p class="eyebrow">Agent Invocation · v1</p>
<h1 class="title">把任意 System Agent<br>变成一个可调用的接口</h1>
<p class="lede">LemonBoss 上的每一个 System Agent —— 无论是挂在某家公司名下，还是像 <code>h3-video-prompt</code> 这样的全局 specialist —— 都可以被外部系统当作一个异步任务接口来调用：传参、拿任务号、轮询结果。跟调用一个 LLM API 的心智模型一致，只是执行体是一个会思考、会用工具的 Agent，单次任务通常要跑几十秒到几分钟。</p>
<div class="pipeline" role="img" aria-label="调用流程：发起请求，进入队列，Agent 执行中，任务完成">
<div class="pipe-step" data-state="request">
<div class="pipe-label">Step 1</div>
<div class="pipe-verb">POST /invoke</div>
</div>
<div class="pipe-step" data-state="queued">
<div class="pipe-label">Step 2 · queued</div>
<div class="pipe-verb">拿到 jobId</div>
</div>
<div class="pipe-step" data-state="running">
<div class="pipe-label">Step 3 · running</div>
<div class="pipe-verb">Agent 执行中</div>
</div>
<div class="pipe-step" data-state="completed">
<div class="pipe-label">Step 4 · completed</div>
<div class="pipe-verb">GET 轮询拿结果</div>
</div>
</div>
</section>
<section id="auth">
<h2><span class="h2-num">01</span> 身份验证</h2>
<p class="section-dek">每一次请求都要在 Header 里带上 API Key —— 系统级 Key（<code>OPEN_API_KEYS</code> 配置）或某个用户账号自己的 Key，两者等效。</p>
<div class="table-wrap">
<table>
<thead><tr><th>Header</th><th>格式</th><th>备注</th></tr></thead>
<tbody>
<tr><td><code>Authorization</code></td><td><code>Bearer <API_KEY></code></td><td>推荐写法</td></tr>
<tr><td><code>X-API-Key</code></td><td><code><API_KEY></code></td><td>等效的备选写法</td></tr>
</tbody>
</table>
</div>
<p style="font-size:14px; color:var(--ink-soft); margin-top:-8px;">Key 不对或没带 → <code>401 Unauthorized</code>。</p>
</section>
<section id="endpoints">
<h2><span class="h2-num">02</span> 两种调用形态</h2>
<p class="section-dek">选哪一条，只取决于目标 Agent 挂不挂在某家公司名下。请求体、响应结构、轮询方式两者完全一致，区别只在地址和归属校验。</p>
<div class="compare">
<div class="compare-card">
<h4>公司级 Agent</h4>
<p><code>POST /companies/:companyId/agents/:agentId/invoke</code></p>
<p class="who">这家公司必须已经雇过这个 Agent（否则 404）。</p>
</div>
<div class="compare-card">
<h4>全局 Agent</h4>
<p><code>POST /agents/:agentId/invoke</code></p>
<p class="who">不挂公司的系统级 specialist（如 <code>h3-video-prompt</code>）。只查 Agent 本体是否存在，不查雇佣关系。<code>agentId</code> 不能带 <code>companyId:</code> 前缀，带了会 400。</p>
</div>
</div>
</section>
<section id="invoke">
<h2><span class="h2-num">03</span> 发起调用</h2>
<p class="section-dek">POST 一次任务描述，接口立刻返回一个 <code>jobId</code>，不会等 Agent 跑完再响应。</p>
<div class="endpoint-card">
<div class="endpoint-head">
<span class="verb">POST</span>
<span class="endpoint">/api/open/agents/:agentId/invoke</span>
</div>
<div class="endpoint-body">
<div class="table-wrap">
<table>
<thead><tr><th>字段</th><th>类型</th><th></th><th>说明</th></tr></thead>
<tbody>
<tr><td><code>task</code></td><td class="mono">string</td><td class="req">必填</td><td>用自然语言描述这次要 Agent 做什么。</td></tr>
<tr><td><code>contextFiles</code></td><td class="mono">array</td><td class="opt">选填</td><td><code>{name, content}</code> 对象数组，作为附件喂给 Agent（见「携带上下文」）。</td></tr>
<tr><td><code>webhookUrl</code></td><td class="mono">string</td><td class="opt">选填</td><td>任务终态时主动 POST 结果到这个地址，免去轮询。</td></tr>
</tbody>
</table>
</div>
<div class="code-block">
<div class="code-label"><span>cURL</span><button class="copy-btn" data-copy="invoke">复制</button></div>
<pre id="invoke"><span class="tok-comment"># 全局 Agent —— 不需要先建公司、不需要先雇佣</span>
curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
-H <span class="tok-str">"Authorization: Bearer sk-your-key"</span> \
-H <span class="tok-str">"Content-Type: application/json"</span> \
-d <span class="tok-str">'{
"task": "写一条 5 秒产品特写镜头的提示词，主体是一杯冒热气的咖啡"
}'</span></pre>
</div>
<div class="code-block">
<div class="code-label"><span>Response · 202 Accepted</span><button class="copy-btn" data-copy="invoke-res">复制</button></div>
<pre id="invoke-res">{
<span class="tok-key">"jobId"</span>: <span class="tok-str">"job-1787655618610-e367c068"</span>,
<span class="tok-key">"status"</span>: <span class="tok-str">"queued"</span>,
<span class="tok-key">"message"</span>: <span class="tok-str">"Agent invocation job queued. Poll GET /api/open/jobs/job-... for status."</span>
}</pre>
</div>
<p class="endpoint-note">把 <code>jobId</code> 存下来——下一步全靠它。</p>
</div>
</div>
</section>
<section id="poll">
<h2><span class="h2-num">04</span> 轮询结果</h2>
<p class="section-dek">建议每 3～5 秒查一次，直到 <code>status</code> 变成终态（<code>completed</code> 或 <code>failed</code>）。</p>
<div class="endpoint-card">
<div class="endpoint-head">
<span class="verb get">GET</span>
<span class="endpoint">/api/open/jobs/:jobId</span>
</div>
<div class="endpoint-body">
<div class="code-block">
<div class="code-label"><span>cURL</span><button class="copy-btn" data-copy="poll">复制</button></div>
<pre id="poll">curl https://lemonboss.wudaima.com/api/open/jobs/job-1787655618610-e367c068 \
-H <span class="tok-str">"Authorization: Bearer sk-your-key"</span></pre>
</div>
<div class="code-block">
<div class="code-label"><span>Response · completed</span><button class="copy-btn" data-copy="poll-res">复制</button></div>
<pre id="poll-res">{
<span class="tok-key">"jobId"</span>: <span class="tok-str">"job-1787655618610-e367c068"</span>,
<span class="tok-key">"status"</span>: <span class="tok-str">"completed"</span>,
<span class="tok-key">"progress"</span>: <span class="tok-str">"Invocation completed"</span>,
<span class="tok-key">"result"</span>: {
<span class="tok-key">"output"</span>: <span class="tok-str">"你好，我是 H3视频提示词专家 🎬 —— 专为 MiniMax H3……"</span>
}
}</pre>
</div>
</div>
</div>
</section>
<section id="status">
<h2><span class="h2-num">05</span> 任务状态参考</h2>
<p class="section-dek">轮询时判断这四个 <code>status</code> 取值：</p>
<dl class="status-grid">
<dt><span class="badge queued">queued</span></dt>
<dd>已接收，正在排队等待执行槽位。</dd>
<dt><span class="badge running">running</span></dt>
<dd>Agent 正在思考/执行，<code>progress</code> 字段会给出简短进展描述。</dd>
<dt><span class="badge completed">completed</span></dt>
<dd>已完成，<code>result.output</code> 里是最终文本结果。</dd>
<dt><span class="badge failed">failed</span></dt>
<dd>执行失败，看 <code>error</code> 字段定位原因。</dd>
</dl>
</section>
<section id="memory">
<h2><span class="h2-num">06</span> 携带上下文</h2>
<p class="section-dek">Agent 不会跨调用自动记住上一次说过什么。想让它接着上次的结果继续干活，把上一轮的输出通过 <code>contextFiles</code> 传回来。</p>
<div class="code-block">
<div class="code-label"><span>下一轮调用的 Body</span><button class="copy-btn" data-copy="memory">复制</button></div>
<pre id="memory">{
<span class="tok-key">"task"</span>: <span class="tok-str">"基于昨天的日志总结，开展新一轮数据清理"</span>,
<span class="tok-key">"contextFiles"</span>: [
{ <span class="tok-key">"name"</span>: <span class="tok-str">"logs-yesterday.txt"</span>, <span class="tok-key">"content"</span>: <span class="tok-str">"……昨日任务输出……"</span> },
{ <span class="tok-key">"name"</span>: <span class="tok-str">"data.csv"</span>, <span class="tok-key">"content"</span>: <span class="tok-str">"id,name\n1,apple"</span> }
]
}</pre>
</div>
<div class="callout"><strong>外部系统充当记忆保管员</strong> —— 拿到 <code>result.output</code> 后自己存起来，下次调用再喂回去。文件按文本落地，支持上万字，这样每个 Agent 都能被当成可控、随时插拔的函数来编排。</div>
</section>
<section id="example">
<h2><span class="h2-num">07</span> 完整示例</h2>
<p class="section-dek">下面这次调用真实跑过：从发起请求到拿到结果，全程 5 秒。</p>
<div class="worked-example">
<div class="we-step">
<div class="we-num">01</div>
<div class="we-body">
<h4>发起调用</h4>
<div class="code-block">
<div class="code-label"><span>Request</span><button class="copy-btn" data-copy="ex1">复制</button></div>
<pre id="ex1">curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
-H <span class="tok-str">"X-API-Key: sk-your-key"</span> -H <span class="tok-str">"Content-Type: application/json"</span> \
-d <span class="tok-str">'{"task": "用一句话自我介绍一下你是做什么的"}'</span></pre>
</div>
</div>
</div>
<div class="we-step">
<div class="we-num">02</div>
<div class="we-body">
<h4>立即拿到 jobId <span class="badge queued" style="margin-left:6px;">queued</span></h4>
<div class="code-block">
<div class="code-label"><span>Response · 202</span><button class="copy-btn" data-copy="ex2">复制</button></div>
<pre id="ex2">{ <span class="tok-key">"jobId"</span>: <span class="tok-str">"job-1787655618610-e367c068"</span>, <span class="tok-key">"status"</span>: <span class="tok-str">"queued"</span> }</pre>
</div>
</div>
</div>
<div class="we-step">
<div class="we-num">03</div>
<div class="we-body">
<h4>约 5 秒后轮询命中 <span class="badge completed" style="margin-left:6px;">completed</span></h4>
<div class="code-block">
<div class="code-label"><span>Response · GET /jobs/:jobId</span><button class="copy-btn" data-copy="ex3">复制</button></div>
<pre id="ex3">{
<span class="tok-key">"status"</span>: <span class="tok-str">"completed"</span>,
<span class="tok-key">"result"</span>: {
<span class="tok-key">"output"</span>: <span class="tok-str">"你好，我是 H3视频提示词专家 🎬 —— 专为 MiniMax H3（海螺）
视频生成模型撰写高质量结构化提示词，把你的视频创意翻译成
H3 能一次读懂的英文结构化描述……把你想拍的内容告诉我，
我就帮你写好成片提示词。"</span>
}
}</pre>
</div>
</div>
</div>
</div>
</section>
<section id="errors">
<h2><span class="h2-num">08</span> 错误参考</h2>
<div class="table-wrap">
<table>
<thead><tr><th>状态码</th><th>触发条件</th></tr></thead>
<tbody>
<tr><td class="mono">400</td><td>缺 <code>task</code> 字段；或对全局端点传了带 <code>companyId:</code> 前缀的 <code>agentId</code>。</td></tr>
<tr><td class="mono">401</td><td>API Key 缺失或无效。</td></tr>
<tr><td class="mono">404</td><td>Agent 不存在；或公司级调用里这家公司没雇过这个 Agent。</td></tr>
<tr><td class="mono">409</td><td>（仅 <code>/jobs/:jobId/result</code>）任务还没到 <code>completed</code>。</td></tr>
</tbody>
</table>
</div>
</section>
<footer class="page-foot">
LemonBoss Open API · Agent Invocation · 内部真相来源见仓库 <code>docs/done/open-api-manual.md</code>
</footer>
</main>
</div>
<script>
document.querySelectorAll('.copy-btn').forEach(function (btn) {
btn.addEventListener('click', function () {
var target = document.getElementById(btn.getAttribute('data-copy'));
if (!target) return;
var text = target.innerText;
var done = function () {
var original = btn.textContent;
btn.textContent = '已复制';
btn.classList.add('copied');
setTimeout(function () { btn.textContent = original; btn.classList.remove('copied'); }, 1400);
};
try {
if (navigator.clipboard && navigator.clipboard.writeText) {
navigator.clipboard.writeText(text).then(done).catch(function () { fallbackCopy(text, done); });
} else {
fallbackCopy(text, done);
}
} catch (e) { fallbackCopy(text, done); }
});
});
function fallbackCopy(text, done) {
var ta = document.createElement('textarea');
ta.value = text; ta.style.position = 'fixed'; ta.style.opacity = '0';
document.body.appendChild(ta); ta.select();
try { document.execCommand('copy'); } catch (e) {}
document.body.removeChild(ta);
done();
}
</script>