快速接入

本指南帮助你在几分钟内完成 EvoLink 的第一次调用。多模态任务使用异步任务模式；文本模型使用同步消息接口，适合直接接入对话和编程工具。

图像生成

使用 GPT Image 2 创建图像生成任务，并通过任务接口查询结果。

视频生成

使用 Seedance 2.0 创建文生视频、图生视频和参考生视频任务。

文本生成

使用 Claude Messages API 获取同步文本响应。

准备工作

创建 API Key

进入 EvoLink 控制台，创建并保存你的 API Key。

选择 Base URL

图像、视频、音频等多模态任务使用 https://api.evolink.ai；文本模型推荐使用 https://direct.evolink.ai。

提交请求

多模态接口会先返回任务 ID；文本接口会直接返回模型回复。

API Key 具有账户调用权限，请只保存在服务端或安全的环境变量中。不要把密钥写入前端代码、公开仓库或客户端安装包。

调用流程

多模态任务遵循同一个流程：

1. 提交任务

调用图像、视频或音频接口，立即获得任务 ID，即响应中的 id 字段。

2. 查询状态

使用 GET /v1/tasks/{task_id} 查询 pending、processing、completed 或 failed。

3. 获取结果

任务完成后从 results 字段读取生成文件 URL。

图像和视频结果链接通常有有效期，建议在任务完成后尽快转存到你自己的对象存储或业务系统。

图像生成

使用 GPT Image 2 创建一个图像生成任务：

curl -X POST https://api.evolink.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "黄昏时分未来都市天际线的电影级广角镜头",
    "size": "16:9",
    "resolution": "4K",
    "quality": "high",
    "n": 1
  }'

成功后会返回任务对象：

{
  "id": "task-unified-1757156493-imcg5zqt",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "status": "pending",
  "progress": 0,
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  }
}

查询任务状态：

curl https://api.evolink.ai/v1/tasks/task-unified-1757156493-imcg5zqt \
  -H "Authorization: Bearer YOUR_API_KEY"

任务完成后，结果会出现在 results 数组中：

{
  "id": "task-unified-1757156493-imcg5zqt",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "status": "completed",
  "progress": 100,
  "results": [
    "https://example.com/generated-image.png"
  ]
}

视频生成

使用 Seedance 2.0 创建文生视频任务：

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-text-to-video",
    "prompt": "微距镜头对准叶片上翠绿的玻璃蛙，焦点逐渐转移到透明腹部，一颗红色心脏正在规律跳动。",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

视频任务同样通过任务接口查询：

curl https://api.evolink.ai/v1/tasks/YOUR_VIDEO_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

如果你需要图生视频或多参考生视频，可以从 Seedance 2.0 全参数指南进入对应接口文档。

文本生成

Claude 文本模型推荐使用 https://direct.evolink.ai，接口路径为 /v1/messages：

curl -X POST https://direct.evolink.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍 EvoLink 的价值"
      }
    ]
  }'

文本接口会同步返回消息对象：

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5-20250929",
  "content": [
    {
      "type": "text",
      "text": "EvoLink 提供统一的 AI 服务网关..."
    }
  ],
  "stop_reason": "end_turn"
}

Python 示例

下面的示例包含提交图像任务、轮询任务状态和读取结果的完整流程：

import os
import time
import requests

API_KEY = os.environ["EVOLINK_API_KEY"]
BASE_URL = "https://api.evolink.ai"

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


def create_image_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers=headers,
        json={
            "model": "gpt-image-2",
            "prompt": prompt,
            "size": "1:1",
            "quality": "high",
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


def wait_for_task(task_id: str, timeout_seconds: int = 300):
    started_at = time.time()

    while time.time() - started_at < timeout_seconds:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "completed":
            return task["results"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "任务失败"))

        time.sleep(5)

    raise TimeoutError("任务执行超时")


task_id = create_image_task("一张干净的产品海报，白色背景，柔和布光")
results = wait_for_task(task_id)
print(results[0])

请求频率限制

EvoLink 的请求频率限制按模型维度配置。不同模型的 RPM、并发数和任务提交限制可能不同，具体取决于模型类型、上游服务容量、账号等级以及实时可用性。轻量级文本模型通常支持更高的请求频率，而图片、视频等生成类模型由于任务耗时更长、上游资源占用更高，限制可能相对较低。对于异步生成类模型，接口成功返回仅表示任务已被接收或创建，不代表任务已完成。高并发业务场景建议在服务端实现队列，并通过任务查询接口或回调获取最终结果。如果持续遇到 HTTP 429 错误，或业务需要更高 RPM / 并发限制，请联系 support@evolink.ai。我们会根据实际使用场景和上游可用容量进行评估。

生产环境建议

密钥管理

使用环境变量或密钥管理服务保存 API Key，并为不同环境配置独立密钥。

任务轮询

根据任务类型设置合理轮询间隔。图像任务可以更频繁，视频任务建议降低轮询频率。

错误处理

处理 failed 状态和 HTTP 错误码，并为频率限制、余额不足、参数错误提供明确提示。

结果转存

生成结果 URL 有有效期，生产环境应尽快下载并存储到自己的文件系统。

下一步

图像 API

查看 GPT Image 2 的完整参数、示例和返回结构。

视频 API

查看 Seedance 2.0 文生视频、图生视频和参考生视频能力。

任务管理

查看任务状态查询、结果字段和错误结构。

​快速接入

图像生成

视频生成

文本生成

​准备工作

​调用流程

1. 提交任务

2. 查询状态

3. 获取结果

​图像生成

​视频生成

​文本生成

​Python 示例

​请求频率限制

​生产环境建议

密钥管理

任务轮询

错误处理

结果转存

​下一步

图像 API

视频 API

任务管理

快速接入

准备工作

调用流程

图像生成

视频生成

文本生成

Python 示例

请求频率限制

生产环境建议

下一步