📄 API Access Documentation
If you want to integrate GUID.AI's chat, image, video, audio, and other capabilities into your own website, backend, scripts, workflows, or third-party tools, we recommend using the current system's **V1 Open API**, which is called uniformly through `/v1/*` paths. API integration can be understood as 5 simple steps: 1. Log in to your account and create an API Key 2. Confirm that your account balance or quota is normal 3. Call `/v1/models` to view models available to the current key 4. Call text, image, video, or audio APIs based on your scenario 5. Debug and launch based on returned results and error messages --- ### 1. What Do You Need Before API Integration? Before starting integration, we recommend confirming the following items: | Preparation Item | Description | | --- | --- | | Platform account | You need to log in before creating an API Key | | API Key | Authentication credential for calling `/v1/*` APIs, usually starting with `sk-` | | Available balance or quota | API calls and web creation usually share the same account balance | | Server-side environment | Store the API Key in a backend, script, or secure environment variable | | Target model | Visible models may differ between keys, so check the model list first | > Reminder: API Keys should not be placed in frontend pages, public repositories, screenshots, chat records, or browser local scripts. --- ### 2. Step 1: Obtain an API Key In the current system, an API Key may also be displayed as **API key**, **token**, or **Token**. How to obtain it: 1. Log in to your account. 2. Go to the top **Skills / MCP Access** page. 3. Open the **Go to Key Management / API Token Management** page. 4. Click **Create Key**. 5. Fill in the key name and configure as needed: - Call quota - Expiration time - Model restrictions - IP whitelist 6. After creation succeeds, copy and save the full key. Put it uniformly in the request header: ```http Authorization: Bearer sk-your-api-key ``` --- ### 3. Step 2: Confirm Base URL and Authentication Method The unified rules for the current system's public API are as follows: | Item | Description | | --- | --- | | Base URL | Your gateway domain, such as `https://your-domain.com` | | API prefix | `/v1/*` | | Authentication method | `Authorization: Bearer sk-xxx` | | Common request format | `application/json` | | Streaming response | Text APIs support `text/event-stream` (SSE) | That means actual call addresses usually look like this: ```text https://your-domain.com/v1/chat/completions https://your-domain.com/v1/images/generations https://your-domain.com/v1/videos ``` --- ### 4. Step 3: Call the Model List API First Before integrating business APIs, the most recommended first call is: ```bash curl https://your-domain.com/v1/models \ -H "Authorization: Bearer sk-your-api-key" ``` This API is used to: 1. Verify whether the API Key is valid 2. Confirm which models the current key can see 3. Confirm what capabilities each model supports After success, it usually returns: - `success: true` - `data[]` model list - Each model's `id` - Each model's supported `supported_endpoint_types` We recommend using the `data[].id` returned here for the `model` field in later requests. --- ### 5. Step 4: Choose APIs by Scenario The current system's public capabilities are mainly divided into 5 categories: | Scenario | Method | Path | Description | | --- | --- | --- | --- | | Model list | `GET` | `/v1/models` | Get models available to the current key | | Text chat | `POST` | `/v1/chat/completions` | Most commonly used, suitable for chat, writing, Q&A, and tool calls | | Text completion | `POST` | `/v1/completions` | Compatible with the older prompt completion method | | Responses conversation | `POST` | `/v1/responses` | Multi-turn, structured output, and reasoning scenarios | | Image generation | `POST` | `/v1/images/generations` | Text-to-image | | Image editing | `POST` | `/v1/images/edits` | Image editing and image-to-image | | Video generation | `POST` | `/v1/videos` | Create asynchronous video tasks | | Video query | `GET` | `/v1/videos/{task_id}` | Query task status | | Video download | `GET` | `/v1/videos/{task_id}/content` | Download video or cover | | Multimodal video | `POST` | `/v1/guidai/videos` | Enhanced modes such as image-to-video, first-and-last frames, and continuation | | Speech synthesis | `POST` | `/v1/audio/speech` | Text-to-speech | | Voice list | `GET` | `/v1/audio/voice/{model}` | Query available voices for a TTS model | If this is your first integration, we recommend the following order: 1. `/v1/models` 2. `/v1/chat/completions` 3. `/v1/images/generations` 4. `/v1/videos` 5. `/v1/audio/speech` --- ### 6. Most Common Integration Examples #### 1. Text Chat This is the most commonly used API and is recommended first for new projects. ```bash curl https://your-domain.com/v1/chat/completions \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [ {"role": "user", "content": "Help me write a product introduction"} ] }' ``` Suitable scenarios: - AI chat - Copywriting - Coding assistance - Structured output - Multi-model application wrappers #### 2. Image Generation ```bash curl https://your-domain.com/v1/images/generations \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "dall-e-3", "prompt": "A cat sitting by the window, morning light, cinematic feel", "size": "1024x1024", "response_format": "url" }' ``` Suitable scenarios: - Text-to-image - Poster generation - Product image creation - Visual asset production #### 3. Video Generation Video APIs are usually **asynchronous tasks** and require 3 steps: ```bash # 1. Create a task curl https://your-domain.com/v1/videos \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "sora-2", "prompt": "A cat walking by the sea at sunset, cinematic camera style", "size": "1280x720", "seconds": 8 }' ``` ```bash # 2. Query status curl https://your-domain.com/v1/videos/task_xxx \ -H "Authorization: Bearer sk-your-api-key" ``` ```bash # 3. Download result curl -L https://your-domain.com/v1/videos/task_xxx/content \ -H "Authorization: Bearer sk-your-api-key" \ -o output.mp4 ``` #### 4. Text-to-Speech We recommend querying voices first, then starting speech synthesis: ```bash curl https://your-domain.com/v1/audio/voice/tts-1 \ -H "Authorization: Bearer sk-your-api-key" ``` ```bash curl https://your-domain.com/v1/audio/speech \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "Welcome to the speech synthesis service", "voice": "alloy", "response_format": "mp3" }' \ -o speech.mp3 ``` --- ### 7. Which Text API Should You Use? Many developers hesitate between the 3 text APIs during first integration. You can choose like this: | API | When to Use | | --- | --- | | `/v1/chat/completions` | Use it by default for most new projects | | `/v1/completions` | Use it when you need compatibility with older systems or older SDKs | | `/v1/responses` | Use it when you need multi-turn context, reasoning, structured output, or enhanced tool calling | If you are not sure yet, start directly with `/v1/chat/completions`. It is usually the safest choice. --- ### 8. Common Response Formats During Integration #### 1. Text APIs They usually return JSON, where the most common fields are: - `choices` - `message` - `content` - `usage` #### 2. Streaming Text APIs If you pass `stream: true`, the response is usually `text/event-stream`, which is an SSE stream. #### 3. Image APIs They usually return generated result information and the corresponding `usage`. #### 4. Video APIs When creating a task, they first return: - `id` - `status` - `progress` Then poll the status through the query API. #### 5. Audio APIs TTS usually returns a binary audio stream directly, not JSON. --- ### 9. What Should You Know About Billing and Quota? In the current system, API calls usually check: 1. Whether the API Key is valid 2. Whether the user status is normal 3. Whether the balance or quota is sufficient 4. Whether an IP whitelist restriction is hit 5. Whether model restrictions or quota restrictions for the key are exceeded Also note: - Visible models may differ between API Keys - Different models may use different billing methods - Text is usually billed by tokens - Images may be billed per generation - Videos may be billed per generation or by duration If you are launching in production, we recommend: - Split keys by environment - Set quota limits for test keys - Set an IP whitelist for production keys - Regularly check wallet balance and consumption records --- ### 10. How Do You Troubleshoot Common Errors? | Symptom | Common Cause | Recommended Solution | | --- | --- | --- | | `401` | API Key is wrong, Bearer is missing, or the key is invalid | Check the `Authorization` request header and key status | | `403` | Insufficient permission, IP whitelist restriction, or unavailable model | Check IP, model permissions, and account status | | `400` | Missing parameters or wrong format | Check fields such as `model`, `messages`, `prompt`, and `voice` | | `404` | Wrong path or task does not exist | Check the URL and whether `task_id` is correct | | `429` | Upstream load is high or requests are too frequent | Reduce frequency and retry later | | `500` | Upstream or gateway internal exception | Record request parameters and response content, then retry later or contact the administrator | You can troubleshoot in this order: 1. Check whether the key is correct first 2. Then check the Base URL and API path 3. Then check whether `model` comes from `/v1/models` 4. Then check balance, quota, and IP whitelist 5. Finally check the request body field format --- ### 11. Security Recommendations Before Launch To avoid API Key leakage or misuse, we recommend: 1. Do not hard-code API Keys in frontend code 2. Store them only in backend environment variables or configuration centers 3. Create different keys for development, testing, and production 4. Set different quota limits for different projects 5. Enable IP whitelist for production keys 6. Rotate long-term keys regularly 7. If leakage is suspected, immediately delete the old key and recreate one --- ### 12. Recommended Integration Path If you are a backend developer, we recommend this path: ```text Create an API Key | ├─ Call /v1/models ├─ Select a text model ├─ Run /v1/chat/completions successfully ├─ Integrate image / video / audio as needed └─ Then implement quota limits, whitelists, exception retries, and logging ``` If you are building an Agent or automation workflow, you can further integrate Skills or MCP after running the API successfully. --- ### Frequently Asked Questions | Question | Answer | | --- | --- | | Are API Key and login session the same thing? | No. When calling `/v1/*` public APIs, use an API Key instead of a web login session. | | Are API and web creation balances the same? | They usually share the same account balance system. | | Why can I enter the API page but calls still fail? | The key may be invalid, quota may be insufficient, an IP whitelist may restrict it, model permissions may not match, or request body fields may be wrong. | | Why does the video API not directly return an mp4? | Because video generation is usually asynchronous. Create a task first, query status, then download the result. | | Which API should I integrate first? | Start with `GET /v1/models`, then `POST /v1/chat/completions`. | | Why do I still get an error after passing a model name? | The model may not be visible to the current key. Check `/v1/models` first. | | How do I enable streaming output? | Pass `stream: true` in the text request body. The server usually returns SSE. | | Why does the audio API not return JSON? | Because TTS returns a binary audio stream. | --- ### One-Sentence Summary In the current system, the safest API integration path is: **create an API Key first, use `/v1/models` to confirm available models, then run the first call through `/v1/chat/completions`, and gradually integrate image, video, and audio capabilities.**

