# IMA Upload API Reference

Full API flow for uploading markdown articles to the IMA `daily` knowledge base. Used in Phase 7 of the reader-digest-flow.

## Credentials

```
IMA_OPENAPI_CLIENTID  - from reader .env or user-provided
IMA_OPENAPI_APIKEY    - from reader .env or user-provided
IMA_DAILY_KNOWLEDGE_BASE_ID - daily KB UUID
```

The `ima-skill` v1.1.7+ ships with `ima_api.cjs` for credential loading.
Legacy auth header: `ima-openapi-ctx: skill_version=1.1.7`.

Do NOT export the full API key in shell commands — use `execute_code` with `subprocess.run` and Python string variables.

## Flow (3 steps)

### 1. create_media

```
POST https://ima.qq.com/openapi/wiki/v1/create_media
Headers: ima-openapi-clientid, ima-openapi-apikey, Content-Type: application/json
Body: { file_name, file_size, content_type, knowledge_base_id, file_ext }
Returns: { code: 0, data: { media_id, cos_credential: { secret_id, secret_key, token, bucket_name, region, cos_key, start_time, expired_time } } }
```

`file_ext` is without the dot (e.g. `md` not `.md`).
`file_name` must be the user-facing article title + `.md`.
`content_type` for markdown is `text/markdown`; media_type=7.

### 2. COS upload

Use `cos-upload.cjs` from `ima-skill/knowledge-base/scripts/`:

```
node <skill_dir>/knowledge-base/scripts/cos-upload.cjs \
  --file <local_md_file> \
  --secret-id <from create_media> \
  --secret-key <from create_media> \
  --token <from create_media> \
  --bucket <bucket_name> \
  --region <region> \
  --cos-key <cos_key> \
  --content-type text/markdown \
  --start-time <start_time> \
  --expired-time <expired_time>
```

⚠️ Must use Python `subprocess.run(args=[...])` to avoid shell parameter mangling.
⚠️ Always capture `returncode` and `stderr` — COS may return exit 0 on HTTP 500.

### 3. add_knowledge

```
POST https://ima.qq.com/openapi/wiki/v1/add_knowledge
Headers: same as create_media
Body: { media_type: 7, media_id, title: "<file_name>", knowledge_base_id, file_info: { cos_key, file_size, file_name } }
```

`media_type=7` for markdown. `title` MUST equal `file_name`.

## Article Markdown reformatting (before upload)

Generated summaries from `reader` have `Source:` and `Category:` header lines.
Before uploading, reformat to IMA style:

```
原文链接：<original article URL>

## 核心结论
...

## 主要论点
...
```

Remove `Source:`, `Category:` lines. Keep `原文链接:` at top with the URL on the next line.
Break long prose (>200 chars per paragraph) into shorter paragraphs for IMA readability.