\r \r

Doc to Slides\r

\r Convert text content or document files into PDF slide presentations using the Ruyi Converter API.\r \r Base URL: https://www.nyoi.io\r \r

Credential check\r

\r

1. If you have an API key (rk_ prefix) from a previous interaction:\r a. Check identity: GET https://www.nyoi.io/api/agent/identity (X-Api-Key header)\r b. If valid → proceed to "Core workflow"\r c. If 403 (expired) or 401 (invalid) → obtain a new credential (step 2)\r
2. To obtain a new credential:\r a. GET https://www.nyoi.io/api/agent/invite-code → get an invite code\r b. POST https://www.nyoi.io/api/agent/activate\r Body: { "inviteCode": "\x3Ccode>", "name": "\x3Cchoose a name>" }\r → returns apiKey (rk_xxx, shown only once)\r c. If 409 (name taken), pick a different name\r d. If 404 (no invite codes), ask user to contact the administrator\r
3. Tell the user the API key so they can note it if desired\r \r The agent identity expires after a period of inactivity (configured by the server).\r Each API call resets the inactivity timer. If expired, the name is released and\r can be re-registered with a new invite code.\r \r ---\r \r

Core workflow\r

\r

Input formats\r

\r Three ways to provide content:\r \r Option 1: Plain text (most common)\r

{\r
  "text": "# Heading\
\
## Section 1\
Content...\
\
## Section 2\
Content...",\r
  "title": "My Presentation",\r
  "language": "en"\r
}\r
```\r
\r
**Option 2: File URLs**\r
```json\r
{\r
  "files": ["https://example.com/report.docx"],\r
  "title": "Project Report",\r
  "language": "en"\r
}\r
```\r
\r
**Option 3: Base64 encoded** (\x3C 10MB)\r
```json\r
{\r
  "files": ["data:application/pdf;base64,AAAA..."],\r
  "title": "My Presentation"\r
}\r
```\r
\r
### Parameters\r
\r
| Parameter | Type | Required | Default | Description |\r
|-----------|------|----------|---------|-------------|\r
| `text` | string | either text or files | - | Text content |\r
| `files` | string[] | either text or files | - | File URLs or Base64 strings |\r
| `title` | string | no | `"Presentation"` | Slide deck title |\r
| `language` | string | no | `"en"` | Output language (ISO 639-1 code) |\r
\r
### Submit job\r
\r
```bash\r
curl -s -X POST https://www.nyoi.io/api/tools/doc-to-slides/execute \\r
  -H "Content-Type: application/json" \\r
  -H "X-Api-Key: \x3CAPI_KEY>" \\r
  -d '\x3CJSON body>'\r
```\r
\r
Response:\r
```json\r
{\r
  "success": true,\r
  "data": {\r
    "jobId": "job_xxx",\r
    "toolId": "doc-to-slides",\r
    "status": "pending"\r
  }\r
}\r
```\r
\r
### Poll job status\r
\r
```bash\r
curl -s https://www.nyoi.io/api/jobs/\x3CjobId>\r
```\r
\r
No authentication required. Slide generation typically takes **8–16 minutes** and may take up to **30 minutes** for large documents. Poll every 30 seconds until `status` is `completed` or `failed`.\r
\r
Status flow: `pending` -> `queued` -> `assigned` -> `running` -> `completed` / `failed`\r
\r
### Download result\r
\r
On completion, `artifacts[0].url` contains a pre-signed download link (PDF), valid for 2 hours.\r
\r
```json\r
{\r
  "data": {\r
    "status": "completed",\r
    "artifacts": [{\r
      "type": "slides",\r
      "url": "https://cos.example.com/output/slides.pdf?sign=xxx",\r
      "expiresAt": "2026-03-17T20:00:00Z",\r
      "expiresIn": 7200\r
    }]\r
  }\r
}\r
```\r
\r
### Deliver the file to the user\r
\r
> **IMPORTANT**: Do NOT just output the URL as text. You must send the PDF file through your messaging platform.\r
\r
1. Check what tools you have for sending messages or files (e.g. a `message` / `send` / `reply` tool that accepts `media`, `file`, `file_url`, or similar parameters).\r
2. Use that tool to send `artifacts[0].url` as a **file or media attachment** so the user receives the PDF directly in the chat.\r
3. Only fall back to displaying the URL as text if you truly have no file-sending capability.\r
\r
The link is valid for 2 hours. If it expires, re-request `GET /api/jobs/\x3CjobId>` for a fresh URL.\r
\r
---\r
\r
## Error handling\r
\r
| Scenario | Status | Action |\r
|----------|--------|--------|\r
| No invite codes available | 404 | Ask user to join the Discord for help: https://discord.gg/uk6q2uPfpg |\r
| Invite code already used | 409 | Claim a new code and retry |\r
| Name already taken | 409 | Pick a different name |\r
| Agent identity expired | 403 | Activate with a new invite code |\r
| Invalid API Key | 401 | Activate with a new invite code |\r
| Daily quota exhausted (20/day) | 429 | Inform user to try again tomorrow |\r
| Tool not allowed for agent | 403 | Agent accounts can only use doc-to-slides |\r
| Job still running after 30 min | - | Ask user to check service status or join Discord: https://discord.gg/uk6q2uPfpg |\r
| Job failed | - | Read the error field from the job response |\r
\r
---\r
\r
## Supported languages\r
\r
Use ISO 639-1 codes for the `language` parameter:\r
\r
| Code | Language |\r
|------|----------|\r
| `en` | English |\r
| `zh-CN` | 中文（简体） |\r
| `zh-TW` | 中文（繁體） |\r
| `ja` | 日本語 |\r
| `ko` | 한국어 |\r
| `es` | español |\r
| `fr` | français |\r
| `de` | Deutsch |\r
| `it` | italiano |\r
| `pt` | português |\r
| `ru` | русский |\r
| `ar` | العربية |\r
\r
---\r
\r
## Support\r
\r
If something isn't working or you need invite codes, join our Discord: https://discord.gg/uk6q2uPfpg\r
\r
---\r
\r
For full API reference with request/response examples, read `{baseDir}/references/api-reference.md`.\r