Choosing an Integration
Choose V1 Open API, Skills, or MCP based on your use case
Guid AI provides multiple integration paths. Pick the option that best matches your scenario.
1. Comparing the three options
| Dimension | V1 Open API | Skills | MCP Service |
|---|---|---|---|
| Path | /v1/* | Install the guid-ai-skills package | /mcp |
| Auth | Bearer Token | GUIDAI_API_KEY environment variable | Bearer Token |
| Typical users | Third-party apps, SDKs | Claude, Cursor, Codex, OpenClaw, etc. | Agents that support MCP |
| Text chat | ✅ 3 endpoints | ❌ | ❌ |
| Image generation | ✅ | ✅ Text-to-image | ✅ |
| Video generation | ✅ including guidai | ✅ including guidai multimodal | ✅ Standard + polling |
| Video download | ✅ content | ✅ Auto-download | ❌ (URL) |
| TTS | ✅ Binary | ✅ Save local file | ✅ (URL) |
| Streaming SSE | ✅ Text endpoints | ❌ | ❌ |
Summary:
- Need SDK integration, text endpoints, guidai multimodal, or direct binary download → use V1 Open API
- Need to generate images/video/audio inside an Agent conversation → use Skills (install
guid-ai-skills) - Need MCP protocol access (configure
/mcpwithout installing a skill package) → use MCP Service
2. Choosing V1 API capabilities
Text: which of the three endpoints?
| Endpoint | Use when |
|---|---|
POST /v1/chat/completions | General chat, tool calling, multimodal input, streaming SSE |
POST /v1/completions | Legacy text completion (prompt → continuation) |
POST /v1/responses | Multi-turn Responses, reasoning, structured output, tool calling |
Most new projects should prefer Chat Completions.
See Text API.
Video: which create path?
| Endpoint | Use when |
|---|---|
POST /v1/videos | Standard video creation (sora, etc.), JSON or multipart |
POST /v1/guidai/videos | Multimodal video: mode + assets[] (first frame, reference images, extend, etc.) |
Query and download always use GET /v1/videos/{task_id} and GET /v1/videos/{task_id}/content.
See Videos API.
Audio: recommended call order
GET /v1/audio/voice/{model}— list available voicesPOST /v1/audio/speech— synthesize usingdata[].codeas thevoiceparameter
See Audio API.
3. Skills / MCP vs REST capability matrix
| Capability | REST | Skills (guid-ai-skills) | MCP Tool | Notes |
|---|---|---|---|---|
| Model list | ✅ | ✅ | list_models | — |
| Text-to-image | ✅ | ✅ | generate_image | — |
| Image edit | ✅ | ❌ | edit_image | REST / MCP only |
| Standard video | ✅ | ✅ | create_video | Skills includes polling and download |
| guidai multimodal video | ✅ | ✅ | ❌ | Skills supports 7 modes |
| Voice list + TTS | ✅ | ✅ | list_audio_voices / text_to_speech | — |
| Text chat | ✅ | ❌ | ❌ | Agent-native or REST |
4. Decision flow
Need to integrate into your own application?
├─ Yes → V1 Open API
└─ No → Generate images/video/audio inside an Agent conversation?
├─ Yes → Install the Skills package (guid-ai-skills)
│ or configure the MCP service (/mcp)
└─ No → Choose V1 API, Skills, or MCP based on the specific scenario