V2Fun API 文档

简体中文

English

简体中文

English

Appearance

快速使用 ​

本指南将帮助你在几分钟内完成第一次 API 调用。

1、创建 API Key ​

V2Fun 使用 API Key 进行身份验证。前往 API Console，登录或注册对应站点的 V2Fun 账号，然后点击“创建 API Key”。 创建成功后，请立即复制并妥善保存完整 Key；关闭弹窗后将无法再次查看。已有有效 Key 且已保存完整值的用户，可直接继续下一步。 符合条件的账号首次成功创建 API Key 后，可获赠 100 API 积分，每账号限领一次。

2、鉴权 ​

所有 API 请求都需要通过 Bearer Token 进行鉴权。请在 HTTP 标头中包含您的 API 密钥，Authorization 如下所示：

http
Authorization: Bearer YOUR_API_KEY

3、发送第一个请求 ​

下面我们通过文本生成图像接口发起第一个请求：

bash
curl -X POST "https://api.v2fun.ai/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image",
    "prompt": "A beautiful sunset over the mountains",
    "size": "1024x1024"
  }'
javascript
const response = await fetch("https://api.v2fun.ai/api/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "qwen-image",
    prompt: "A beautiful sunset over the mountains",
    size: "1024x1024"
  })
});

const data = await response.json();
console.log(data);
python
import requests

url = "https://api.v2fun.ai/api/v1/images/generations"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "qwen-image",
    "prompt": "A beautiful sunset over the mountains",
    "size": "1024x1024"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
java
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String body = "{\"model\":\"qwen-image\",\"prompt\":\"A beautiful sunset over the mountains\",\"size\":\"1024x1024\"}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.v2fun.ai/api/v1/images/generations"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

4、响应示例 ​

V2Fun API 采用任务机制，大多数请求会立即返回一个 task_uuid，用于后续查询任务状态和结果。

json
{
  "task_uuid": "fa3c24dc-22bf-4163-9ab9-f9836b605638",
  "task_type": "image_generation",
  "model": "qwen-image",
  "status": "QUEUED",
  "created_at": 1715358176,
  "queue_position": 0,
  "estimated_queue_time": 0
}

5、查询任务结果 ​

由于 API 采用任务机制，结果通常是异步返回的。你可以使用任务 ID 查询结果。

Endpoint ​

GET https://api.v2fun.ai/api/v1/images/generations/{task_uuid}

请求示例 ​

bash
curl -X GET "https://api.v2fun.ai/api/v1/images/generations/{task_uuid}" \
  -H "Authorization: Bearer YOUR_API_KEY"
javascript
const response = await fetch(
  `https://api.v2fun.ai/api/v1/images/generations/${task_uuid}`,
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data);
python
import requests

url = f"https://api.v2fun.ai/api/v1/images/generations/{task_uuid}"

headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())
java
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.v2fun.ai/api/v1/images/generations/" + taskUuid))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

响应示例 ​

json
{
  "task_uuid": "fa3c24dc-22bf-4163-9ab9-f9836b605638",
  "task_type": "image_generation",
  "model": "qwen-image",
  "status": "COMPLETED",
  "created_at": 1715358176,
  "completed_at": 1715358276,
  "result": [
    "images/9b895fbe-cb3c-4704-aaba-bbd717f3f16e.png"
  ],
  "metadata": {
    "downloads": [
      {
        "asset_path": "images/9b895fbe-cb3c-4704-aaba-bbd717f3f16e.png",
        "download_url": "https://asset.v2fun.ai/download/images/9b895fbe-cb3c-4704-aaba-bbd717f3f16e.png",
        "download_expires_at": 1786525274
      }
    ]
  }
}

使用说明 ​

  • 你可能需要轮询该接口直到任务完成。建议每 2–5 秒轮询一次，避免频繁请求。
  • 当 status = COMPLETED 时，result 字段中包含最终结果。

后续步骤 ​

现在您已经成功发出了第一个 API 请求，不妨探索以下场景化指南，了解如何将 V2Fun 的原子化 API 串联为生产力工具：

提示

点击下方场景，查看完整的 API 串联逻辑、代码示例以及最佳实践。