📄 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:

Log in to your account and create an API Key
Confirm that your account balance or quota is normal
Call /v1/models to view models available to the current key
Call text, image, video, or audio APIs based on your scenario
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:

Log in to your account.
Go to the top Skills / MCP Access page.
Open the Go to Key Management / API Token Management page.
Click Create Key.
Fill in the key name and configure as needed:
- Call quota
- Expiration time
- Model restrictions
- IP whitelist
After creation succeeds, copy and save the full key.

Put it uniformly in the request header:

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:

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:

curl https://your-domain.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

This API is used to:

Verify whether the API Key is valid
Confirm which models the current key can see
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:

/v1/models
/v1/chat/completions
/v1/images/generations
/v1/videos
/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.

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

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:

# 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
  }'

# 2. Query status
curl https://your-domain.com/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-your-api-key"

# 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:

curl https://your-domain.com/v1/audio/voice/tts-1 \
  -H "Authorization: Bearer sk-your-api-key"

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:

Whether the API Key is valid
Whether the user status is normal
Whether the balance or quota is sufficient
Whether an IP whitelist restriction is hit
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:

Check whether the key is correct first
Then check the Base URL and API path
Then check whether model comes from /v1/models
Then check balance, quota, and IP whitelist
Finally check the request body field format

11. Security Recommendations Before Launch

To avoid API Key leakage or misuse, we recommend:

Do not hard-code API Keys in frontend code
Store them only in backend environment variables or configuration centers
Create different keys for development, testing, and production
Set different quota limits for different projects
Enable IP whitelist for production keys
Rotate long-term keys regularly
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:

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.