获取任务状态

curl --request GET \
  --url https://api.vidgo.ai/api/generate/status/{task_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vidgo.ai/api/generate/status/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vidgo.ai/api/generate/status/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidgo.ai/api/generate/status/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vidgo.ai/api/generate/status/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "<string>"
}

GET

api

generate

status

{task_id}

获取任务状态

curl --request GET \
  --url https://api.vidgo.ai/api/generate/status/{task_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vidgo.ai/api/generate/status/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vidgo.ai/api/generate/status/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidgo.ai/api/generate/status/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vidgo.ai/api/generate/status/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "<string>"
}

查询图像、视频、音频和 3D 生成任务，并在任务完成后获取返回的全部文件。

接口

GET https://api.vidgo.ai/api/generate/status/{task_id}

认证

该接口目前通过 task_id 查询任务，不要求 Authorization 请求头，也不校验任务归属。示例中带上了 Bearer 请求头，以便与需要认证的提交请求共用同一套客户端配置。

Authorization: Bearer VIDGO_API_KEY

获取 API Key

在控制台生成你的 API Key

参数

路径参数

参数	类型	必填	说明
`task_id`	string	是	提交接口返回的任务唯一标识

响应

成功响应（200）

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

响应字段

字段	类型	说明
`code`	integer	HTTP 状态码（成功为 200）
`data.task_id`	string	任务唯一标识
`data.status`	string	任务状态：`not_started`、`running`、`finished`、`failed`
`data.files`	array	生成的媒体文件（状态为 `finished` 时返回）
`data.files[].file_url`	string	生成文件的直接 URL
`data.files[].file_type`	string	产物类型：`image`、`video`、`audio`、`lyrics`、`3d` 或 `other`
`data.files[].watermark_url`	string	可选，带水印的版本
`data.files[].label`	string	可选，产物角色，例如模型、预览或时间戳
`data.files[].format`	string	可选，文件格式
`data.files[].content_type`	string	可选，MIME 类型
`data.files[].file_name`	string	可选，文件名
`data.files[].file_size`	integer	可选，文件大小（字节）
`data.files[].metadata`	object	可选，额外的产物元数据
`data.created_time`	string	任务创建时间（ISO 8601 时间戳）
`data.progress`	integer or null	服务提供时的完成百分比；部分任务在完成前可能一直为 0
`data.error_message`	string or null	有错误信息时返回错误描述；没有错误时为 null

状态值

状态	说明
`not_started`	任务已排队，等待处理
`running`	任务正在生成中
`finished`	任务已成功完成，结果在 `files` 中
`failed`	任务失败，错误详情在 `error_message` 中

各状态响应示例

未开始

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": null
  }
}

运行中（图像）

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "running",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 45,
    "error_message": null
  }
}

已完成（图像）

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

已完成（视频）

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "finished",
    "files": [
      {
        "file_url": "https://file.goseaapp.com/videos/video-xyz789.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}

失败

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "failed",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": "The prompt violates our content policy"
  }
}

代码示例

cURL

curl -X GET https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  -H "Authorization: Bearer VIDGO_API_KEY"

Python

import requests

API_KEY = "your-api-key-here"
task_id = "task-unified-1757165031-uyujaw3d"

response = requests.get(
    f"https://api.vidgo.ai/api/generate/status/{task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

result = response.json()
data = result["data"]

print(f"Status: {data['status']}")
print(f"Progress: {data['progress']}%")

if data["status"] == "finished":
    for file in data["files"]:
        print(f"Generated file: {file['file_url']}")
elif data["status"] == "failed":
    print(f"Error: {data['error_message']}")

JavaScript / Node.js

const API_KEY = 'your-api-key-here';
const taskId = 'task-unified-1757165031-uyujaw3d';

const response = await fetch(
  `https://api.vidgo.ai/api/generate/status/${taskId}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const result = await response.json();
const data = result.data;

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

if (data.status === 'finished') {
  data.files.forEach(file => {
    console.log(`Generated file: ${file.file_url}`);
  });
} else if (data.status === 'failed') {
  console.log(`Error: ${data.error_message}`);
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const (
    APIKey = "your-api-key-here"
    BaseURL = "https://api.vidgo.ai"
)

type APIResponse struct {
    Code int      `json:"code"`
    Data TaskData `json:"data"`
}

type TaskData struct {
    TaskID       string      `json:"task_id"`
    Status       string      `json:"status"`
    Files        []MediaFile `json:"files"`
    CreatedTime  string      `json:"created_time"`
    Progress     int         `json:"progress"`
    ErrorMessage *string     `json:"error_message"`
}

type MediaFile struct {
    FileURL  string `json:"file_url"`
    FileType string `json:"file_type"`
}

func main() {
    taskID := "task-unified-1757165031-uyujaw3d"

    req, _ := http.NewRequest(
        "GET",
        fmt.Sprintf("%s/api/generate/status/%s", BaseURL, taskID),
        nil,
    )
    req.Header.Set("Authorization", "Bearer "+APIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var apiResp APIResponse
    json.Unmarshal(body, &apiResp)

    data := apiResp.Data
    fmt.Printf("Status: %s\n", data.Status)
    fmt.Printf("Progress: %d%%\n", data.Progress)

    if data.Status == "finished" {
        for _, file := range data.Files {
            fmt.Printf("Generated file: %s\n", file.FileURL)
        }
    } else if data.Status == "failed" {
        fmt.Printf("Error: %s\n", *data.ErrorMessage)
    }
}

Java

import java.net.http.*;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;

public class VidgoAPI {
    private static final String API_KEY = "your-api-key-here";
    private static final String BASE_URL = "https://api.vidgo.ai";

    public static void main(String[] args) throws Exception {
        String taskId = "task-unified-1757165031-uyujaw3d";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/generate/status/" + taskId))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        ObjectMapper mapper = new ObjectMapper();
        JsonNode root = mapper.readTree(response.body());
        JsonNode data = root.get("data");

        String status = data.get("status").asText();
        int progress = data.get("progress").asInt();

        System.out.println("Status: " + status);
        System.out.println("Progress: " + progress + "%");

        if ("finished".equals(status)) {
            JsonNode files = data.get("files");
            files.forEach(file -> {
                System.out.println("Generated file: " + file.get("file_url").asText());
            });
        } else if ("failed".equals(status)) {
            System.out.println("Error: " + data.get("error_message").asText());
        }
    }
}

PHP

<?php

$apiKey = 'your-api-key-here';
$taskId = 'task-unified-1757165031-uyujaw3d';
$baseUrl = 'https://api.vidgo.ai';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/api/generate/status/$taskId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey"
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
$data = $result['data'];

echo "Status: {$data['status']}\n";
echo "Progress: {$data['progress']}%\n";

if ($data['status'] === 'finished') {
    foreach ($data['files'] as $file) {
        echo "Generated file: {$file['file_url']}\n";
    }
} elseif ($data['status'] === 'failed') {
    echo "Error: {$data['error_message']}\n";
}

Ruby

require 'net/http'
require 'json'
require 'uri'

api_key = 'your-api-key-here'
task_id = 'task-unified-1757165031-uyujaw3d'
base_url = 'https://api.vidgo.ai'

uri = URI("#{base_url}/api/generate/status/#{task_id}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)
data = result['data']

puts "Status: #{data['status']}"
puts "Progress: #{data['progress']}%"

if data['status'] == 'finished'
  data['files'].each do |file|
    puts "Generated file: #{file['file_url']}"
  end
elsif data['status'] == 'failed'
  puts "Error: #{data['error_message']}"
end

轮询最佳实践

轮询任务完成状态时，请遵循以下建议：

轮询间隔：每 2-5 秒查询一次状态。避免更频繁地轮询，以免触发速率限制。

超时：设置超时以避免无限循环。典型生成耗时：

图像：15-60 秒
视频：90-300 秒

指数退避：遇到速率限制（429）或服务器错误（5xx）时，使用指数退避（等待 1 秒、2 秒、4 秒、8 秒……）。

完整轮询示例

import requests
import time

API_KEY = "your-api-key-here"
BASE_URL = "https://api.vidgo.ai"

def wait_for_completion(task_id, timeout=600, poll_interval=2):
    """
    Wait for task completion with timeout

    Args:
        task_id: Task identifier
        timeout: Maximum wait time in seconds
        poll_interval: Seconds between checks

    Returns:
        Task data when complete

    Raises:
        TimeoutError: If timeout exceeded
        RuntimeError: If task failed
    """
    start_time = time.time()
    headers = {"Authorization": f"Bearer {API_KEY}"}

    while True:
        # Check timeout
        if time.time() - start_time > timeout:
            raise TimeoutError(f"Task did not complete within {timeout}s")

        # Get status
        response = requests.get(
            f"{BASE_URL}/api/generate/status/{task_id}",
            headers=headers
        )

        if response.status_code == 429:
            # Rate limited - wait longer
            time.sleep(poll_interval * 2)
            continue

        response.raise_for_status()
        result = response.json()
        data = result["data"]

        # Log progress
        elapsed = int(time.time() - start_time)
        print(f"[{elapsed}s] Status: {data['status']}, Progress: {data['progress']}%")

        # Check completion
        if data["status"] == "finished":
            print("Task completed successfully")
            return data
        elif data["status"] == "failed":
            raise RuntimeError(f"Task failed: {data['error_message']}")

        time.sleep(poll_interval)

# Usage
try:
    task_id = "task-unified-1757165031-uyujaw3d"
    result = wait_for_completion(task_id)

    for file in result["files"]:
        print(f"Download: {file['file_url']}")

except TimeoutError as e:
    print(f"Timeout: {e}")
except RuntimeError as e:
    print(f"Error: {e}")

错误响应

HTTP 错误码

状态码	说明	处理方式
404	Not Found	任务 ID 不存在
500	Server Error	使用指数退避重试

错误响应格式

{
  "detail": "Task not found"
}

重要说明

内容有效期：文件的有效期取决于存储服务商。需要长期保留的输出请及时下载并保存。

积分：积分在提交任务时扣除。如果任务失败，这部分积分会自动退还。

Webhook：除了轮询，你也可以在提交任务时提供 callback_url 以自动接收通知。参见Webhook 回调。

后续步骤

提交任务

了解如何提交生成任务

图像生成

使用 GPT-4o 生成图像

视频生成

使用 Sora 2 创建视频

快速开始

完整集成指南

其他生成文件

音频和 3D 工作流使用同一个 files 数组。file_type 可能是 audio、3d、image 或 other。该数组会保留模型资产、预览图、纹理、动画文件和时间戳文件。每一项还可能包含 label、format、content_type、file_name、file_size 和 metadata。请处理返回的每一个文件；metadata 字段是可选的。

授权

Authorization

string

header

必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

路径参数

task_id

string

必填

任务唯一标识

响应

成功获取任务状态

code

integer

必填

HTTP 状态码

示例:

200

data

object

必填

Show child attributes

​接口

​认证

获取 API Key

​参数

​路径参数

​响应

​成功响应（200）

​响应字段

​状态值

​各状态响应示例

​未开始

​运行中（图像）

​已完成（图像）

​已完成（视频）

​失败

​代码示例

​cURL

​Python

​JavaScript / Node.js

​Go

​Java

​PHP

​Ruby

​轮询最佳实践

​完整轮询示例

​错误响应

​HTTP 错误码

​错误响应格式

​重要说明

​后续步骤

提交任务

图像生成

视频生成

快速开始

​其他生成文件

授权

路径参数

响应

接口

认证

参数

路径参数

响应

成功响应（200）

响应字段

状态值

各状态响应示例

未开始

运行中（图像）

已完成（图像）

已完成（视频）

失败

代码示例

cURL

Python

JavaScript / Node.js

Go

Java

PHP

Ruby

轮询最佳实践

完整轮询示例

错误响应

HTTP 错误码

错误响应格式

重要说明

后续步骤

其他生成文件