> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 完成第一次 Vidgo API 调用：创建 API Key，提交图像、视频或音乐生成任务，并轮询任务状态获取结果。

## 欢迎使用 Vidgo API

Vidgo API 提供强大的图像和视频生成 API。本指南将帮助你在几分钟内完成第一次 API 调用。

## 第 1 步：获取 API Key

1. 访问 [Vidgo API 控制台](https://vidgo.ai/apis/dashboard/api-key)
2. 登录或创建账户
3. 生成新的 API Key
4. **重要**：复制并妥善保存你的 API Key，它只会显示一次

## 第 2 步：生成第一张图片

所有 API 请求都需要在 `Authorization` 请求头中携带 API Key。完整示例如下：

```python theme={null}
import requests

url = "https://api.vidgo.ai/api/generate/submit"
headers = {
    "Authorization": "Bearer VIDGO_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4o-image",
    "callback_url": "https://your-domain.com/callback",
    "input": {
        "prompt": "A serene mountain landscape at sunset with vibrant colors",
        "size": "1:1",
        "n": 1
    }
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()
task_id = result["data"]["task_id"]
print(f"Task ID: {task_id}")
```

```javascript theme={null}
const response = await fetch('https://api.vidgo.ai/api/generate/submit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer VIDGO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-image',
    callback_url: 'https://your-domain.com/callback',
    input: {
      prompt: 'A serene mountain landscape at sunset with vibrant colors',
      size: '1:1',
      n: 1
    }
  })
});

const result = await response.json();
const taskId = result.data.task_id;
console.log(`Task ID: ${taskId}`);
```

```bash theme={null}
curl -X POST https://api.vidgo.ai/api/generate/submit \
  -H "Authorization: Bearer $VIDGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-image",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A serene mountain landscape at sunset with vibrant colors",
      "size": "1:1",
      "n": 1
    }
  }'
```

## 第 3 步：查询任务状态

Vidgo API 采用异步处理。轮询状态接口即可获取结果：

```python theme={null}
import requests
import time

task_id = "task-unified-1757165031-uyujaw3d"
url = f"https://api.vidgo.ai/api/generate/status/{task_id}"
headers = {
    "Authorization": "Bearer VIDGO_API_KEY"
}

# Poll until complete
while True:
    response = requests.get(url, headers=headers)
    result = response.json()
    task = result["data"]

    status = task['status']
    progress = task.get('progress', 0)

    print(f"Status: {status}, Progress: {progress}%")

    if status == 'finished':
        print(f"Image URL: {task['files'][0]['file_url']}")
        break
    elif status == 'failed':
        print(f"Error: {task['error_message']}")
        break

    time.sleep(2)  # Wait 2 seconds before next check
```

```javascript theme={null}
const taskId = 'task-unified-1757165031-uyujaw3d';

async function checkStatus() {
  while (true) {
    const response = await fetch(
      `https://api.vidgo.ai/api/generate/status/${taskId}`,
      {
        headers: {
          'Authorization': 'Bearer VIDGO_API_KEY'
        }
      }
    );

    const result = await response.json();
    const task = result.data;
    const { status, progress, files, error_message } = task;

    console.log(`Status: ${status}, Progress: ${progress}%`);

    if (status === 'finished') {
      console.log('Image URL:', files[0].file_url);
      break;
    } else if (status === 'failed') {
      console.log('Error:', error_message);
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

checkStatus();
```

```bash theme={null}
curl -X GET https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  -H "Authorization: Bearer $VIDGO_API_KEY"
```

**响应示例：**

```json theme={null}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "progress": 100,
    "files": [
      {
        "file_url": "https://file.goseaapp.com/images/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "error_message": null
  }
}
```

> [!NOTE]
>
> **内容有效期**：生成的文件有效期为 24 小时，请及时下载保存。

## 第 4 步：尝试视频生成

用同样的方式生成视频，只需更换模型和输入参数：

```python theme={null}
payload = {
    "model": "kwaivgi/kling-v3.0-std/text-to-video",
    "callback_url": "https://your-domain.com/callback",
    "input": {
        "prompt": "A time-lapse of a bustling city street transitioning from day to night",
        "duration": 5,
        "aspect_ratio": "16:9",
        "sound": True
    }
}
```

## 第 5 步：尝试音乐生成

生成可自定义风格和人声的音乐：

```python theme={null}
payload = {
    "model": "generate-music",
    "callback_url": "https://your-domain.com/callback",
    "input": {
        "prompt": "A calm and relaxing piano track with soft melodies",
        "style": "Classical",
        "title": "Peaceful Piano Meditation",
        "custom_mode": True,
        "instrumental": True,
        "mv": "V5"
    }
}
```

## 支持

需要帮助？我们随时为你提供协助：

* **邮箱**：[support@vidgo.ai](mailto:support@vidgo.ai)
* **控制台**：[vidgo.ai](https://vidgo.ai/apis)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.