Async API - YeLin AI

Async Endpoint: https://api.yelinai.com/v1/videosCall Method: Three steps (Create Task → Query Status → Get Video)Advantages: More Stable | Task Queue | Long-running Tasks Support Important Difference - Image-to-Video Upload MethodAsync API differs significantly from Sync API for image-to-video:

Feature	Sync API	Async API
Image Upload	Supports URL or Base64	Local file only
Request Format	JSON	multipart/form-data

If you have an image URL: Download it locally first, then upload via Async API.Example Comparison:

{/* Sync API - Supports URL */}
"image_url": {"url": "https://example.com/image.png"}

{/* Async API - Local file only */}
files = {'input_reference': open('/path/to/image.png', 'rb')}

Why Choose Async API?

Higher Stability

Task queue based, avoiding long connection timeout issues

No Charge on Failure ⭐

Key Advantage: No charges for failures of any kind

✓ Content violation → No charge
✓ Queue timeout → No charge
✓ Generation failure → No charge

Sync API charges as long as request succeeds (HTTP 200), even if generation ultimately fails!

Flexible Polling

Query task status and progress anytime

Parameterized Control

Specify resolution and duration via parameters, more flexible

Sync vs Async Comparison

Feature	Sync API	Async API (Recommended)
Call Method	Single request, wait for completion	Create task then poll for results
Endpoint	`/v1/chat/completions`	`/v1/videos`
Resolution	Model name (`sora_video2-landscape`)	Parameter (`size: "1280x720"`)
Duration	Model name (`sora_video2-15s`)	Parameter (`seconds: "15"`)
Image-to-Video	Supports image URL	Local file upload only
Failed Billing	Charged even if generation fails	⭐ No charge on failure
Stability	Depends on long connection	⭐⭐⭐⭐⭐ More Stable
Progress	Stream output	Poll for progress percentage
Timeout	Needs long timeout setting	Task runs independently, no timeout limit
Use Cases	Quick testing, real-time feedback	Production environment, batch generation

Recommended to use Async API, especially in production environments or when batch generating videos, for better stability.

Quick Start

Async calling consists of three steps: 1 Create Video Task POST request to create task, get task ID 2 Query Task Status Periodically poll to check generation progress 3 Download Video Retrieve video file after task completes

Complete Example

Step 1: Create Task (Text-to-Video) Step 1: Create Task (Image-to-Video) Step 2: Query Status Step 3: Download Video

curl -X POST "https://api.yelinai.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cute cat playing with a ball in a sunny garden",
    "size": "1280x720",
    "seconds": "15"
  }'

# Response example
{
  "id": "video_abc123",
  "object": "task",
  "model": "sora-2",
  "status": "submitted",
  "created_at": 1760945092,
  "expires_at": 1761031492
}

API Endpoints

1. Create Video Task

POST https://api.yelinai.com/v1/videosCreate a new video generation task

Request Parameters

Parameter	Type	Required	Options	Description
`model`	string	✓	`"sora-2"`, `"sora-2-pro"`	Model name
`prompt`	string	✓	-	Video generation prompt
`size`	string	✓	`"1280x720"`, `"720x1280"`	Video resolution (landscape/portrait)
`seconds`	string	✓	`"10"`, `"15"`	Video duration (seconds)
`input_reference`	file	Required for image-to-video	-	Local image file (local upload only) Supported formats: JPG, PNG, WebP Recommended size: 1280x720 Recommended file size: < 5MB

Model Selection

sora-2: Base model, 720P resolution, extremely high stability, $0.15/call
sora-2-pro: HD model, 1080P resolution, generation time ~10 minutes, $0.8/call

Response Fields

Field	Type	Description
`id`	string	Unique task identifier for subsequent queries
`object`	string	Fixed as `"task"`
`model`	string	Model used
`status`	string	Task status: `"submitted"`
`created_at`	integer	Creation timestamp
`expires_at`	integer	Expiration timestamp (24 hours later)

2. Query Task Status

GET https://api.yelinai.com/v1/videos/{video_id}Query current status and progress of video generation task

Path Parameters

Parameter	Type	Required	Description
`video_id`	string	✓	Task ID returned when creating task

Response Fields

Field	Type	Description
`id`	string	Task ID
`object`	string	Fixed as `"video"`
`model`	string	Model used
`status`	string	Task status (see below)
`progress`	integer	Progress percentage (0-100)
`url`	string	Video download path (completed status only)
`created_at`	integer	Creation timestamp
`completed_at`	integer	Completion timestamp (completed status only)
`error`	object	Error information (failed status only)

Task Status

Status	Description	Progress
`submitted`	Submitted, waiting for processing	0%
`in_progress`	Generating	1-99%
`completed`	Generation completed	100%
`failed`	Generation failed	-

3. Get Video Content

GET https://api.yelinai.com/v1/videos/{video_id}/contentDownload completed video file

Path Parameters

Parameter	Type	Required	Description
`video_id`	string	✓	Task ID

Response

Returns binary stream of video file (MP4 format) Important NoticeVideo files are stored for 24 hours only. Please download and save to local storage promptly!

Complete Code Examples

Python Example (with Polling Logic)

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.yelinai.com/v1"

# Step 1: Create video task (text-to-video)
def create_video_task(prompt, size="1280x720", seconds="15"):
    """Create video generation task"""
    url = f"{BASE_URL}/videos"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "sora-2",
        "prompt": prompt,
        "size": size,
        "seconds": seconds
    }

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Step 1: Create video task (image-to-video)
def create_video_task_with_image(prompt, image_path, size="1280x720", seconds="10"):
    """Create image-to-video task"""
    url = f"{BASE_URL}/videos"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    # Ensure file remains open during request
    with open(image_path, 'rb') as image_file:
        files = {
            # Specify filename and MIME type for proper upload
            'input_reference': ('image.png', image_file, 'image/png')
        }
        data = {
            'model': 'sora-2',
            'prompt': prompt,
            'size': size,
            'seconds': seconds
        }

        # Send request within with block to keep file handle valid
        response = requests.post(url, headers=headers, files=files, data=data)
        response.raise_for_status()
        return response.json()

# Step 2: Poll for status
def wait_for_video(video_id, poll_interval=5, timeout=600):
    """Wait for video generation to complete"""
    url = f"{BASE_URL}/videos/{video_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    start_time = time.time()

    while True:
        # Check timeout
        if time.time() - start_time > timeout:
            raise TimeoutError(f"Video generation timeout ({timeout}s)")

        # Query status
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        task = response.json()

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

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

        if status == "completed":
            return task
        elif status == "failed":
            error = task.get("error", {})
            raise Exception(f"Generation failed: {error.get('message', 'Unknown error')}")

        # Wait before retry
        time.sleep(poll_interval)

# Step 3: Download video
def download_video(video_id, save_path="video.mp4"):
    """Download generated video"""
    url = f"{BASE_URL}/videos/{video_id}/content"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    response = requests.get(url, headers=headers, stream=True)
    response.raise_for_status()

    with open(save_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                f.write(chunk)

    print(f"Video saved to: {save_path}")

# Complete workflow (text-to-video)
def generate_video_async(prompt, size="1280x720", seconds="15"):
    """Complete async video generation workflow"""
    print("1. Creating video task...")
    task = create_video_task(prompt, size, seconds)
    video_id = task["id"]
    print(f"   Task ID: {video_id}")

    print("\n2. Waiting for video generation...")
    completed_task = wait_for_video(video_id)
    duration = completed_task['completed_at'] - completed_task['created_at']
    print(f"   Completed! Duration: {duration}s")

    print("\n3. Downloading video...")
    download_video(video_id)
    print("\n✅ Done!")

# Complete workflow (image-to-video)
def generate_video_from_image_async(image_path, prompt, size="1280x720", seconds="10"):
    """Complete workflow for generating video from local image"""
    import os

    if not os.path.exists(image_path):
        print(f"Error: Image file not found {image_path}")
        return None

    print(f"1. Uploading image and creating task... ({image_path})")
    task = create_video_task_with_image(prompt, image_path, size, seconds)
    video_id = task["id"]
    print(f"   Task ID: {video_id}")

    print("\n2. Waiting for video generation...")
    completed_task = wait_for_video(video_id)
    duration = completed_task['completed_at'] - completed_task['created_at']
    print(f"   Completed! Duration: {duration}s")

    print("\n3. Downloading video...")
    download_video(video_id, save_path=f"image_to_video_{video_id}.mp4")
    print("\n✅ Done!")

    return video_id

# Usage examples
if __name__ == "__main__":
    # Text-to-video
    generate_video_async(
        prompt="A cute cat playing with a ball in a sunny garden",
        size="1280x720",  # Landscape
        seconds="15"       # 15 seconds
    )

    # Image-to-video
    generate_video_from_image_async(
        image_path="/path/to/your/image.png",
        prompt="Animate this scene with natural dynamic effects",
        size="1280x720",  # Landscape
        seconds="10"       # 10 seconds
    )

JavaScript/Node.js Example

const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.yelinai.com/v1';

// Create video task (text-to-video)
async function createVideoTask(prompt, size = '1280x720', seconds = '15') {
  const response = await axios.post(`\`$\{BASE_URL}/videos`, {
    model: 'sora-2',
    prompt,
    size,
    seconds
  }, {
    headers: { 'Authorization': `Bearer \`$\{API_KEY}` }
  });

  return response.data;
}

// Create video task (image-to-video)
async function createVideoTaskWithImage(prompt, imagePath, size = '1280x720', seconds = '10') {
  const formData = new FormData();
  formData.append('model', 'sora-2');
  formData.append('prompt', prompt);
  formData.append('size', size);
  formData.append('seconds', seconds);
  formData.append('input_reference', fs.createReadStream(imagePath));

  const response = await axios.post(`\`$\{BASE_URL}/videos`, formData, {
    headers: {
      'Authorization': `Bearer \`$\{API_KEY}`,
      ...formData.getHeaders()
    }
  });

  return response.data;
}

// Poll for status
async function waitForVideo(videoId, pollInterval = 5000, timeout = 600000) {
  const startTime = Date.now();

  while (true) {
    // Check timeout
    if (Date.now() - startTime > timeout) {
      throw new Error(`Video generation timeout (\`$\{timeout/1000}s)`);
    }

    // Query status
    const response = await axios.get(`\`$\{BASE_URL}/videos/\`$\{videoId}`, {
      headers: { 'Authorization': `Bearer \`$\{API_KEY}` }
    });

    const task = response.data;
    const { status, progress = 0 } = task;

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

    if (status === 'completed') {
      return task;
    } else if (status === 'failed') {
      const error = task.error || {};
      throw new Error(`Generation failed: \`$\{error.message || 'Unknown error'}`);
    }

    // Wait before retry
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}

// Download video
async function downloadVideo(videoId, savePath = 'video.mp4') {
  const response = await axios.get(
    `\`$\{BASE_URL}/videos/\`$\{videoId}/content`,
    {
      headers: { 'Authorization': `Bearer \`$\{API_KEY}` },
      responseType: 'stream'
    }
  );

  const writer = fs.createWriteStream(savePath);
  response.data.pipe(writer);

  return new Promise((resolve, reject) => {
    writer.on('finish', () => {
      console.log(`Video saved to: \`$\{savePath}`);
      resolve();
    });
    writer.on('error', reject);
  });
}

// Complete workflow (text-to-video)
async function generateVideoAsync(prompt, size = '1280x720', seconds = '15') {
  try {
    console.log('1. Creating video task...');
    const task = await createVideoTask(prompt, size, seconds);
    const videoId = task.id;
    console.log(`   Task ID: \`$\{videoId}`);

    console.log('\n2. Waiting for video generation...');
    const completedTask = await waitForVideo(videoId);
    const duration = completedTask.completed_at - completedTask.created_at;
    console.log(`   Completed! Duration: \`$\{duration}s`);

    console.log('\n3. Downloading video...');
    await downloadVideo(videoId);
    console.log('\n✅ Done!');

  } catch (error) {
    console.error('Error:', error.message);
  }
}

// Complete workflow (image-to-video)
async function generateVideoFromImageAsync(imagePath, prompt, size = '1280x720', seconds = '10') {
  try {
    if (!fs.existsSync(imagePath)) {
      console.error(`Error: Image file not found \`$\{imagePath}`);
      return null;
    }

    console.log(`1. Uploading image and creating task... (\`$\{imagePath})`);
    const task = await createVideoTaskWithImage(prompt, imagePath, size, seconds);
    const videoId = task.id;
    console.log(`   Task ID: \`$\{videoId}`);

    console.log('\n2. Waiting for video generation...');
    const completedTask = await waitForVideo(videoId);
    const duration = completedTask.completed_at - completedTask.created_at;
    console.log(`   Completed! Duration: \`$\{duration}s`);

    console.log('\n3. Downloading video...');
    await downloadVideo(videoId, `image_to_video_\`$\{videoId}.mp4`);
    console.log('\n✅ Done!');

    return videoId;

  } catch (error) {
    console.error('Error:', error.message);
    return null;
  }
}

// Usage examples
// Text-to-video
generateVideoAsync(
  'A cute cat playing with a ball in a sunny garden',
  '1280x720',  // Landscape
  '15'         // 15 seconds
);

// Image-to-video
generateVideoFromImageAsync(
  '/path/to/your/image.png',
  'Animate this scene with natural dynamic effects',
  '1280x720',  // Landscape
  '10'         // 10 seconds
);

Best Practices

Polling Interval Recommended polling interval: 3-5 seconds

# Recommended
poll_interval = 5  # Query every 5 seconds

# Not recommended
poll_interval = 1  # Too frequent, wastes requests
poll_interval = 30 # Too slow, poor user experience

Reasoning:

Video generation typically takes 2-5 minutes
3-5 seconds provides timely progress feedback
Avoids excessive requests

Timeout Handling Recommended timeout: 10 minutes (600 seconds)

def wait_for_video(video_id, timeout=600):
    start_time = time.time()

    while True:
        if time.time() - start_time > timeout:
            # Timeout handling
            print(f"Task {video_id} timeout, can continue querying later")
            break

        # Query logic...

Note:

Task timeout doesn’t auto-cancel
Can continue querying same video_id later
Task validity period is 24 hours

Retry Strategy Suggested retry logic:

def create_video_with_retry(prompt, max_retries=3):
    for i in range(max_retries):
        try:
            return create_video_task(prompt)
        except Exception as e:
            if i < max_retries - 1:
                print(f"Failed, retrying in 5s... ({i+1}/{max_retries})")
                time.sleep(5)
            else:
                raise

Retry scenarios:

✓ Network errors → Retry
✓ Service busy (503) → Retry
✗ Content violation → Don’t retry, modify prompt
✗ Insufficient balance → Don’t retry, recharge first

Batch Generation Concurrency control recommendations:

import concurrent.futures

def batch_generate_videos(prompts, max_workers=5):
    """Batch generate videos with concurrency control"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        # Create all tasks
        future_to_prompt = {
            executor.submit(create_video_task, prompt): prompt
            for prompt in prompts
        }

        video_ids = []
        for future in concurrent.futures.as_completed(future_to_prompt):
            task = future.result()
            video_ids.append(task['id'])

        # Concurrently wait for all tasks
        futures = [executor.submit(wait_for_video, vid) for vid in video_ids]
        results = [f.result() for f in concurrent.futures.as_completed(futures)]

        return results

Recommendations:

Creating tasks: High concurrency OK (10-30)
Querying status: Recommended concurrency ≤ 10
Downloading videos: Recommended concurrency ≤ 5

Pricing

Async API has exactly the same pricing as Sync API, billed per call.

Parameter Combination	Price	Discounted Rate
10s video (landscape/portrait)	$0.15/call	≈ ¥1.0/call
15s video (landscape/portrait)	$0.15/call	≈ ¥1.0/call
HD (sora-2-pro)	$0.8/call	≈ ¥5.4/call

Billing Rules:

✓ Charged only when video successfully generated (status = “completed”)
✗ Failed, timeout, cancelled not charged
✗ Content safety issues also not charged (important difference from Sync API⭐)
✗ Status queries not charged

Key Advantage of Async API: No charges for failures of any kind, including content safety review failures. Sync API charges as long as the request succeeds, even if generation ultimately fails.

FAQ

How long is task validity? Task validity: 24 hours

After creating task, expires_at field shows expiration time
Can query task status anytime within 24 hours
After video generation completes, file is stored for 24 hours
After 24 hours, task and video will be automatically cleaned

Recommendations:

Download video immediately after completion
Don’t rely on server for long-term storage

How to cancel a running task? Manual task cancellation not currently supported

Once created, task will auto-queue for execution
If no longer needed, simply ignore it
Incomplete tasks won’t be charged

Alternatives:

Wait for task to naturally complete or fail
Task auto-expires after 24 hours

Why do I get 404 when querying? Possible reasons:

Incorrect video_id - Check if fully copied
Task expired - Over 24 hours
Network issues - Retry request

Solution:

try:
    response = client.get(f"/videos/{video_id}")
    task = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Task doesn't exist or expired")
    else:
        raise

Can async and sync APIs be mixed? Yes, they’re completely independentTwo API systems are completely independent:

Different endpoints
Different calling methods
Same pricing
Share same API Key and balance

Usage recommendations:

Quick testing → Use sync API
Production environment → Use async API (more stable)
Batch generation → Use async API

Why isn’t progress field updating? Possible reasons:

Normal - Some processing stages update slowly
Queue waiting - May be queued during peak hours
Task stuck - Rare cases where task may get stuck

Handling:

Continue waiting 5-10 minutes
If no change after 10 minutes, contact support
Provide video_id for troubleshooting

Does image-to-video support image URLs? **No! Only local file upload is supported.**Correct approach:

# ✓ Correct: Upload local file
with open('/path/to/image.png', 'rb') as f:
    files = {'input_reference': f}
    response = requests.post(url, files=files, data=data)

Not supported:

✗ Image URLs
✗ Base64 encoding
✗ Online image links

Reason: Async API uses multipart/form-data format, supporting only local file streams. What image formats are supported? Supported formats:

✓ JPG / JPEG
✓ PNG
✓ WebP

Image requirements:

File size: < 5MB (recommended)
Resolution: Recommended 1280x720 or similar ratio
Source: Must be local file

Auto-detect MIME type:

import os

def get_mime_type(path):
    ext = os.path.splitext(path)[1].lower()
    types = {
        '.jpg': 'image/jpeg',
        '.jpeg': 'image/jpeg',
        '.png': 'image/png',
        '.webp': 'image/webp'
    }
    return types.get(ext, 'image/jpeg')

Is prompt required for image-to-video? **Yes, prompt parameter is required!**Even if you just want the image to “naturally animate”, you need to provide a description:Recommended simple prompts:

"Animate the scene naturally"
"Add dynamic effects while keeping original style"
"Bring this scene to life with gentle motion"

More specific prompts work better:

"Create ripples on the lake, trees swaying in wind, clouds moving slowly"
"Make the cat jump from left to right, tail wagging"
"360-degree slow rotation showcasing the product with lighting effects"

Is image-to-video more expensive? Exactly the same price!

Video Length	Price
10s (landscape/portrait)	$0.15/call ≈ ¥1.0/call
15s (landscape/portrait)	$0.15/call ≈ ¥1.0/call

Billing notes:

Image-to-video and text-to-video cost the same
Only charged when successfully generated
No charge on failure (including format errors, content violations, etc.)

Does image affect generation time? **Almost no impact.**Image-to-video and text-to-video take similar time:

Typical time: 2-5 minutes
Factors: Video length, queue size, complexity

Image size impact:

Recommended < 5MB: Fast upload, fast processing
Large images: Only affects upload time (seconds), no significant impact on generation time

Error Handling

Common Error Codes

HTTP Status	Error Type	Description	Action
400	Bad Request	Invalid request parameters	Check parameter format and values
401	Unauthorized	Invalid API Key	Check Authorization header
402	Payment Required	Insufficient balance	Recharge and retry
404	Not Found	Task doesn’t exist	Check video_id or task expired
429	Too Many Requests	Requests too frequent	Reduce polling frequency
500	Internal Server Error	Server error	Retry later
503	Service Unavailable	Service temporarily unavailable	Wait and retry

Error Response Format

{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

Technical Support

Need Help?

Email: threezhang.cn@gmail.com
WeChat: Kikivivikids
Telegram: https://t.me/laozhang_cn
Documentation:

Next Steps

Sync API

Check out sync API approach

Examples

View more usage examples

Pricing

Learn about detailed pricing

FAQ

View more Q&A

​Why Choose Async API?

​Higher Stability

​No Charge on Failure ⭐

​Flexible Polling

​Parameterized Control

​Sync vs Async Comparison

​Quick Start

​Complete Example

​API Endpoints

​1. Create Video Task

​Request Parameters

​Response Fields

​2. Query Task Status

​Path Parameters

​Response Fields

​Task Status

​3. Get Video Content

​Path Parameters

​Response

​Complete Code Examples

​Python Example (with Polling Logic)

​JavaScript/Node.js Example

​Best Practices

​Pricing

​FAQ

​Error Handling

​Common Error Codes

​Error Response Format

​Technical Support

​Need Help?

​Next Steps

​Sync API

​Examples

​Pricing

​FAQ

Why Choose Async API?

Higher Stability

No Charge on Failure ⭐

Flexible Polling

Parameterized Control

Sync vs Async Comparison

Quick Start

Complete Example

API Endpoints

1. Create Video Task

Request Parameters

Response Fields

2. Query Task Status

Path Parameters

Response Fields

Task Status

3. Get Video Content

Path Parameters

Response

Complete Code Examples

Python Example (with Polling Logic)

JavaScript/Node.js Example

Best Practices

Pricing

FAQ

Error Handling

Common Error Codes

Error Response Format

Technical Support

Need Help?

Next Steps

Sync API

Examples

Pricing

FAQ