API使用指南 - 完整文档

📚 文档概览

本文档提供完整的API接口说明，包括图片生成模型和视频生成模型两大部分。

🎨 图片生成模型（3个接口）

• 文生图接口 - /v1/images/generations
• 图生图接口 - /v1/images/edits
• 多模态对话接口 - /v1/chat/completions

🎬 视频生成模型（3个接口）

• 视频生成接口 - /v1/videos
• 视频状态查询 - /v1/videos/{video_id}
• 视频Remix - /v1/videos/{video_id}/remix

🚀 快速开始

1. API密钥配置

在使用API之前，您需要获取API密钥并进行配置：

export API_KEY="your-api-key-here"
export BASE_URL="https://api.example.com"

2. 认证方式

所有API请求都需要在请求头中包含认证信息：

Authorization: Bearer YOUR_API_KEY

3. 快速示例

以下是一个简单的图片生成请求示例：

curl -X POST https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只可爱的猫咪在花园里玩耍",
    "n": 1,
    "size": "1024x1024"
  }'

4. 基础URL

所有API端点的基础URL为：

https://api.example.com

图片生成模型接口

1.1 文生图接口

POST

/v1/images/generations

📝 接口说明

通过文本描述生成图片，支持多种图片尺寸和格式。适用于根据提示词创建全新的图像内容。

📋 请求参数

参数名	类型	必需	说明
`prompt`	string	是	图片描述文本，建议使用英文以获得更好效果
`model`	string	否	模型ID，如 "flux.1-kontext-dev"、"dall-e-3"
`size`	string	否	图片尺寸，默认 "1024x1024"，支持 "512x512"、"1024x1024"、"1792x1024" 等
`response_format`	string	否	返回格式："url"（图片URL）或 "b64_json"（Base64编码）
`n`	integer	否	生成图片数量，默认为 1，最大为 10

💻 请求示例

cURL:

curl -X POST "https://api.example.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "a beautiful sunset over mountains",
    "size": "1024x1024",
    "response_format": "url",
    "n": 1
  }'

Python:

import requests

url = "https://api.example.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "dall-e-3",
    "prompt": "a beautiful sunset over mountains",
    "size": "1024x1024",
    "response_format": "url",
    "n": 1
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

JavaScript:

const response = await fetch('https://api.example.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'dall-e-3',
    prompt: 'a beautiful sunset over mountains',
    size: '1024x1024',
    response_format: 'url',
    n: 1
  })
});

const result = await response.json();
console.log(result);

✅ 响应示例

{
  "created": 1234567890,
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "revised_prompt": "a beautiful sunset over mountains with vibrant colors"
    }
  ]
}

1.2 图生图接口

POST

/v1/images/edits

📝 接口说明

基于已有图片进行编辑和修改，支持多种图片输入方式。可以对图片进行风格转换、内容修改等操作。

💡 支持的图片输入格式：

URL格式：直接传入图片的HTTP/HTTPS链接
Base64格式：将图片编码为base64字符串（需添加data URI前缀）
文件上传：使用multipart/form-data上传本地文件

📋 请求参数

参数名	类型	必需	说明
`image`	string/file	是	原始图片（URL、base64或文件）
`prompt`	string	是	编辑描述文本，说明如何修改图片
`model`	string	否	模型ID，如 "flux.1-kontext-dev"
`size`	string	否	输出图片尺寸，默认 "1024x1024"
`response_format`	string	否	返回格式："url" 或 "b64_json"

💻 请求示例

方式1：JSON格式（URL方式）

curl -X POST "https://api.example.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux.1-kontext-dev",
    "image": "https://example.com/original-image.jpg",
    "prompt": "change the background to a beach",
    "size": "1024x1024",
    "response_format": "url"
  }'

方式2：FormData格式（文件上传）

curl -X POST "https://api.example.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/image.png" \
  -F "prompt=change the background to a beach" \
  -F "model=flux.1-kontext-dev" \
  -F "size=1024x1024"

方式3：Python（Base64方式）

import requests
import base64

# 读取并编码图片
with open('image.png', 'rb') as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

url = "https://api.example.com/v1/images/edits"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "flux.1-kontext-dev",
    "image": f"data:image/png;base64,{image_base64}",
    "prompt": "change the background to a beach",
    "size": "1024x1024",
    "response_format": "url"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

JavaScript（文件上传）:

const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('prompt', 'change the background to a beach');
formData.append('model', 'flux.1-kontext-dev');
formData.append('size', '1024x1024');

const response = await fetch('https://api.example.com/v1/images/edits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log(result);

✅ 响应示例

{
  "created": 1234567890,
  "data": [
    {
      "url": "https://example.com/edited-image.png",
      "revised_prompt": "original image with background changed to a beach scene"
    }
  ]
}

1.3 多模态对话接口（图片）

POST

/v1/chat/completions

📝 接口说明

通过对话方式生成图片，支持在消息中包含图片URL进行图生图操作。此接口兼容OpenAI的chat completions格式。

⚠️ 注意：使用此接口生成图片时，需要在提示词末尾使用英文中括号指定宽高比，例如：[1024:1024]

📋 请求参数

参数名	类型	必需	说明
`model`	string	是	模型ID，支持图片生成的模型
`messages`	array	是	对话消息数组，可包含文本和图片
`stream`	boolean	否	是否流式返回，默认false

💻 请求示例

文生图示例（cURL）:

curl -X POST "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "messages": [
      {
        "role": "user",
        "content": "帮我画一只宇航猫在月球漫步[1024:1024]"
      }
    ],
    "stream": false
  }'

图生图示例（Python）:

import requests

url = "https://api.example.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "dall-e-3",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "将这张图片的背景改成海滩[1024:1024]"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/original.jpg"
                    }
                }
            ]
        }
    ],

    "stream": false
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

✅ 响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "dall-e-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "https://example.com/generated-image.png"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 1,
    "total_tokens": 21
  }
}

视频生成模型接口

🎬 视频API特性

✅

文生视频、图生视频

支持纯文本描述或基于图片生成视频

✅

视频角色生成

传入视频参数生成角色动画

✅

视频分镜功能

使用特殊格式创建多镜头视频

✅

视频Remix

基于已有视频进行二次创作

✅

异步生成

支持状态查询和进度跟踪

✅

横屏/竖屏自动检测

智能识别视频方向和尺寸

2.1 视频生成接口（异步）

POST

/v1/videos

📝 接口说明

创建视频生成任务，支持多种生成模式。此接口为异步接口，会立即返回任务ID，需要通过查询接口获取生成结果。

💡 支持的生成模式：

文生视频：仅提供prompt参数
图生视频：提供image参数（URL/base64/文件）
视频角色生成：提供video参数
视频分镜：使用特殊格式的prompt（镜头1: ... 镜头2: ...）
视频Remix：提供remix_target_id参数

📋 请求参数

参数名	类型	必需	说明
`model`	string	是	模型名称，如 "sora-2"、"sora-2-landscape"、"sora-2-portrait"
`prompt`	string	是	视频描述文本，支持分镜格式
`image`	string/file	否	图片输入（URL、base64或文件上传），用于图生视频
`video`	string/file	否	视频输入，用于视频角色生成
`remix_target_id`	string	否	Remix目标视频的share_id

💻 请求示例

示例1：文生视频（cURL）

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A serene lake at sunset with mountains in the background"
  }'

示例1：文生视频（Python）

import requests

url = "https://api.example.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "sora-2",
    "prompt": "A serene lake at sunset with mountains in the background"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Video ID: {result['id']}")
print(f"Status: {result['status']}")

示例1：文生视频（JavaScript）

const response = await fetch('https://api.example.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sora-2',
    prompt: 'A serene lake at sunset with mountains in the background'
  })
});

const result = await response.json();
console.log('Video ID:', result.id);
console.log('Status:', result.status);

示例2：图生视频（cURL）

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-landscape",
    "prompt": "Animate this image with gentle camera movement",
    "image": "https://example.com/input-image.jpg"
  }'

示例2：图生视频（Python）

import requests
import base64

# 使用Base64编码的图片
with open('input.jpg', 'rb') as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

url = "https://api.example.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "sora-2-landscape",
    "prompt": "Animate this image with gentle camera movement",
    "image": f"data:image/jpeg;base64,{image_base64}"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Video ID: {result['id']}")

示例2：图生视频（JavaScript）

const response = await fetch('https://api.example.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sora-2-landscape',
    prompt: 'Animate this image with gentle camera movement',
    image: 'https://example.com/input-image.jpg'
  })
});

const result = await response.json();
console.log('Video ID:', result.id);

示例3：视频角色生成（cURL）

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A character walking through a forest",
    "video": "https://example.com/character-video.mp4"
  }'

示例3：视频角色生成（Python）

import requests

url = "https://api.example.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "sora-2",
    "prompt": "A character walking through a forest",
    "video": "https://example.com/character-video.mp4"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Video ID: {result['id']}")

示例3：视频角色生成（JavaScript）

const response = await fetch('https://api.example.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sora-2',
    prompt: 'A character walking through a forest',
    video: 'https://example.com/character-video.mp4'
  })
});

const result = await response.json();
console.log('Video ID:', result.id);

示例4：视频分镜（cURL）

📌 分镜格式说明：使用"镜头X: 描述..."的格式，每个镜头占一行

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "镜头1: 清晨的城市街道，阳光洒在建筑物上\n镜头2: 咖啡店内，顾客正在点餐\n镜头3: 公园里，人们在晨跑锻炼"
  }'

示例4：视频分镜（Python）

import requests

url = "https://api.example.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 分镜格式的prompt
storyboard_prompt = """镜头1: 清晨的城市街道，阳光洒在建筑物上
镜头2: 咖啡店内，顾客正在点餐
镜头3: 公园里，人们在晨跑锻炼"""

data = {
    "model": "sora-2",
    "prompt": storyboard_prompt
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Video ID: {result['id']}")

示例4：视频分镜（JavaScript）

// 分镜格式的prompt
const storyboardPrompt = `镜头1: 清晨的城市街道，阳光洒在建筑物上
镜头2: 咖啡店内，顾客正在点餐
镜头3: 公园里，人们在晨跑锻炼`;

const response = await fetch('https://api.example.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sora-2',
    prompt: storyboardPrompt
  })
});

const result = await response.json();
console.log('Video ID:', result.id);

示例5：FormData格式（文件上传）

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=sora-2-landscape" \
  -F "prompt=Animate this image" \
  -F "image=@/path/to/image.jpg"

✅ 响应示例

{
  "id": "video_abc123def456ghi789",
  "object": "video",
  "created_at": 1234567890,
  "status": "queued",
  "model": "sora-2",
  "prompt": "A serene lake at sunset with mountains in the background",
  "progress": 0,
  "seconds": "15",
  "size": "1280x720"
}

2.2 查询视频状态接口

GET

/v1/videos/{video_id}

📝 接口说明

查询异步视频任务的生成状态和进度。视频生成通常需要几分钟时间，可以通过此接口轮询获取最新状态。

📋 请求参数

参数名	类型	必需	说明
`video_id`	string	是	视频ID，从创建接口返回的id字段

💻 请求示例

cURL:

curl -X GET "https://api.example.com/v1/videos/video_abc123def456ghi789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python:

import requests
import time

video_id = "video_abc123def456ghi789"
url = f"https://api.example.com/v1/videos/{video_id}"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# 轮询查询状态
while True:
    response = requests.get(url, headers=headers)
    result = response.json()
    
    print(f"Status: {result['status']}")
    if result['status'] == 'completed':
        print(f"Video URL: {result['video_url']}")
        break
    elif result['status'] == 'failed':
        print(f"Error: {result.get('error', 'Unknown error')}")
        break
    elif result['status'] == 'in_progress':
        print(f"Progress: {result.get('progress', 0)}%")
    
    time.sleep(10)  # 等待10秒后再次查询

JavaScript:

const videoId = 'video_abc123def456ghi789';

async function checkVideoStatus() {
  const response = await fetch(`https://api.example.com/v1/videos/${videoId}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  
  const result = await response.json();
  console.log('Status:', result.status);
  
  if (result.status === 'completed') {
    console.log('Video URL:', result.video_url);
    return result;
  } else if (result.status === 'failed') {
    console.error('Error:', result.error);
    throw new Error(result.error);
  } else if (result.status === 'in_progress') {
    console.log('Progress:', result.progress + '%');
    // 10秒后再次查询
    await new Promise(resolve => setTimeout(resolve, 10000));
    return checkVideoStatus();
  }
}

checkVideoStatus();

✅ 响应示例

状态1：排队中（queued）

{
  "id": "video_abc123def456ghi789",
  "object": "video",
  "created_at": 1234567890,
  "status": "queued",
  "model": "sora-2",
  "prompt": "A serene lake at sunset with mountains in the background",
  "progress": 0,
  "seconds": "15",
  "size": "1280x720"
}

状态2：生成中（in_progress）

{
  "id": "video_abc123def456ghi789",
  "object": "video",
  "created_at": 1234567890,
  "status": "in_progress",
  "model": "sora-2",
  "prompt": "A serene lake at sunset with mountains in the background",
  "progress": 45,
  "seconds": "15",
  "size": "1280x720"
}

状态3：已完成（completed）

{
  "id": "video_abc123def456ghi789",
  "object": "video",
  "created_at": 1234567890,
  "status": "completed",
  "model": "sora-2",
  "prompt": "A serene lake at sunset with mountains in the background",
  "progress": 100,
  "seconds": "15",
  "size": "1280x720",
  "video_url": "https://example.com/videos/generated-video.mp4",
  "thumbnail_url": "https://example.com/videos/thumbnail.jpg"
}

状态4：失败（failed）

{
  "id": "video_abc123def456ghi789",
  "object": "video",
  "created_at": 1234567890,
  "status": "failed",
  "model": "sora-2",
  "prompt": "A serene lake at sunset with mountains in the background",
  "progress": 0,
  "error": {
    "code": "generation_failed",
    "message": "Video generation failed due to content policy violation"
  }
}

2.3 视频Remix接口

POST

/v1/videos/{video_id}/remix

📝 接口说明

基于已有视频进行二次创作，可以改变视频的风格、场景或内容，同时保持原视频的基本结构和动作。

💡 提示：Remix功能适合对已生成的视频进行风格转换、场景替换等创意改编。

📋 请求参数

参数名	类型	必需	说明
`video_id`	string	是	原视频ID（路径参数）
`prompt`	string	是	Remix提示词，描述如何改编视频

💻 请求示例

cURL:

curl -X POST "https://api.example.com/v1/videos/video_abc123def456ghi789/remix" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform the scene into a cyberpunk style with neon lights"
  }'

Python:

import requests

video_id = "video_abc123def456ghi789"
url = f"https://api.example.com/v1/videos/{video_id}/remix"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "prompt": "Transform the scene into a cyberpunk style with neon lights"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Remix Video ID: {result['id']}")
print(f"Original Video ID: {result['remix_source_id']}")

JavaScript:

const videoId = 'video_abc123def456ghi789';

const response = await fetch(`https://api.example.com/v1/videos/${videoId}/remix`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Transform the scene into a cyberpunk style with neon lights'
  })
});

const result = await response.json();
console.log('Remix Video ID:', result.id);
console.log('Original Video ID:', result.remix_source_id);

✅ 响应示例

{
  "id": "video_xyz789abc456def123",
  "object": "video",
  "created_at": 1234567890,
  "status": "queued",
  "model": "sora-2",
  "prompt": "Transform the scene into a cyberpunk style with neon lights",
  "remix_source_id": "video_abc123def456ghi789",
  "progress": 0,
  "seconds": "15",
  "size": "1280x720"
}

📝 完整示例代码

Python 示例

import requests
import os

# 配置
API_KEY = os.getenv("API_KEY")
BASE_URL = "https://api.example.com"

# 图片生成示例
def generate_image(prompt):
    url = f"{BASE_URL}/v1/images/generations"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "dall-e-3",
        "prompt": prompt,
        "n": 1,
        "size": "1024x1024"
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 视频生成示例
def generate_video(prompt):
    url = f"{BASE_URL}/v1/videos"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "sora-1.0-turbo",
        "prompt": prompt,
        "size": "1280x720"
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
if __name__ == "__main__":
    # 生成图片
    image_result = generate_image("一只可爱的猫咪")
    print("图片生成结果:", image_result)
    
    # 生成视频
    video_result = generate_video("海浪拍打沙滩")
    print("视频生成结果:", video_result)

JavaScript 示例

// 配置
const API_KEY = process.env.API_KEY;
const BASE_URL = "https://api.example.com";

// 图片生成函数
async function generateImage(prompt) {
    const response = await fetch(`${BASE_URL}/v1/images/generations`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            model: 'dall-e-3',
            prompt: prompt,
            n: 1,
            size: '1024x1024'
        })
    });
    
    return await response.json();
}

// 视频生成函数
async function generateVideo(prompt) {
    const response = await fetch(`${BASE_URL}/v1/videos`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            model: 'sora-1.0-turbo',
            prompt: prompt,
            size: '1280x720'
        })
    });
    
    return await response.json();
}

// 使用示例
(async () => {
    // 生成图片
    const imageResult = await generateImage('一只可爱的猫咪');
    console.log('图片生成结果:', imageResult);
    
    // 生成视频
    const videoResult = await generateVideo('海浪拍打沙滩');
    console.log('视频生成结果:', videoResult);
})();