---
name: uapi-integration-patterns
description: uapi data/response Jinja2 templates, input_fields bricks format, and async task response patterns
---

# uapi Integration Patterns

## input_fields — Bricks 格式

**必须用 bricks 兼容数组，不是 JSON Schema：**

```json
[
  {"name":"prompt","label":"提示词","required":true,"uitype":"text"},
  {"name":"image_files","label":"参考图片","uitype":"image"},
  {"name":"resolution","label":"分辨率","uitype":"code","data":[{"value":"768P","text":"768P"},{"value":"2K","text":"2K"}],"defaultvalue":"768P"},
  {"name":"duration","label":"时长","uitype":"code","data":[{"value":5,"text":"5秒"},{"value":10,"text":"10秒"}],"defaultvalue":5}
]
```

## data 模板 (Jinja2)

把 bricks 平铺字段→API 嵌套格式。关键技巧：
- `{{json.dumps(prompt)}}` — JSON 转义
- `{% for img in image_files %}...{% endfor %}` — 遍历
- `{{b64media2url(request, img)}}` — base64→URL
- `{{field or 'default'}}` — 默认值

## response 模板 (async task)

**必须含 `{{json.dumps(output.usage)}}` + SUCCEEDED/FAILED 分支。**

```jinja2
{
{% if output.task_status == 'SUCCEEDED' %}
    "video": "{{downloadfile2url(request, output.video_url)}}",
    "usage": {{json.dumps(output.usage)}},
{% elif output.task_status == 'FAILED' %}
    "error": "{{output.code}}:{{output.message}}",
{% endif %}
    "status": "{{output.task_status}}"
}
```

## 格式参考

**不可猜测**。查看 DB 已有记录：
```python
async with get_sor_context(request._run_ns, 'llmage') as sor:
    recs = await sor.sqlExe(
        "SELECT id, name, data, response FROM uapi WHERE data != '' OR response != '' LIMIT 10", {})
```