API Endpoints
Complete reference for all API endpoints
Video Generation
Text to Video (Standard)
Generate a video from a text prompt.
POST /api/v1/sora2/text-to-videoCredits: 10
Request Body
{
"prompt": "A golden retriever playing fetch in a sunny park",
"negativePrompt": "blurry, low quality",
"aspectRatio": "16:9"
}| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the video (max 2000 chars) |
negativePrompt | string | No | Elements to avoid in the generation |
aspectRatio | string | No | Video aspect ratio: 16:9, 9:16, 1:1 (default: 16:9) |
Response
{
"code": 200,
"msg": "success",
"data": {
"task_id": "task_abc123xyz"
}
}Text to Video (Pro)
Generate a high-quality video with extended options.
POST /api/v1/sora2-pro/text-to-videoCredits (varies by duration and quality):
| Duration | Standard | High |
|---|---|---|
| 10 seconds | 150 | 330 |
| 15 seconds | 270 | 630 |
Request Body
{
"prompt": "Cinematic drone shot over a misty forest at sunrise",
"negativePrompt": "shaky, amateur",
"aspectRatio": "16:9",
"duration": 10,
"quality": "high"
}| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the video |
negativePrompt | string | No | Elements to avoid |
aspectRatio | string | No | 16:9, 9:16, 1:1 |
duration | number | No | Video duration: 10, 15 seconds (default: 10) |
quality | string | No | Quality level: standard, high (default: standard) |
Image to Video (Standard)
Animate an image into a video.
POST /api/v1/sora2/image-to-videoCredits: 10
Request Body
{
"imageUrl": "https://example.com/image.jpg",
"prompt": "The flower slowly blooms and sways in a gentle breeze",
"aspectRatio": "16:9"
}| Parameter | Type | Required | Description |
|---|---|---|---|
imageUrl | string | Yes | URL of the source image (HTTPS only) |
prompt | string | No | Motion description |
negativePrompt | string | No | Elements to avoid |
aspectRatio | string | No | 16:9, 9:16, 1:1 |
Use the /api/v1/upload endpoint to upload images and get a valid URL.
Image to Video (Pro)
Create high-quality animated videos from images.
POST /api/v1/sora2-pro/image-to-videoCredits (varies by duration and quality):
| Duration | Standard | High |
|---|---|---|
| 10 seconds | 150 | 330 |
| 15 seconds | 270 | 630 |
Request Body
{
"imageUrl": "https://example.com/image.jpg",
"prompt": "Dramatic zoom into the subject with light rays",
"duration": 10,
"quality": "high"
}| Parameter | Type | Required | Description |
|---|---|---|---|
imageUrl | string | Yes | URL of the source image |
prompt | string | No | Motion description |
negativePrompt | string | No | Elements to avoid |
aspectRatio | string | No | 16:9, 9:16, 1:1 |
duration | number | No | 10, 15 seconds |
quality | string | No | standard, high |
Watermark Removal
Remove watermarks from Sora-generated videos.
POST /api/v1/sora2/watermark-removeCredits: 10
Request Body
{
"videoUrl": "https://sora.chatgpt.com/g/xxxx/video.mp4"
}| Parameter | Type | Required | Description |
|---|---|---|---|
videoUrl | string | Yes | URL of the Sora video (must start with https://sora.chatgpt.com/) |
Only videos from sora.chatgpt.com are supported for watermark removal.
Storyboard Generation (Pro)
Generate a multi-shot video from structured prompts.
POST /api/v1/sora2-pro/storyboardCredits (varies by duration):
| Duration | Credits |
|---|---|
| 10 seconds | 150 |
| 15 seconds | 270 |
| 25 seconds | 270 |
Request Body
{
"nFrames": "10",
"aspectRatio": "landscape",
"shots": [
{
"Scene": "Wide establishing shot of a futuristic city at night",
"duration": 3
},
{
"Scene": "Close-up of a neon sign flickering",
"duration": 2
},
{
"Scene": "Character walking down a rain-soaked street",
"duration": 5
}
],
"imageUrls": [],
"callBackUrl": "https://your-server.com/webhook"
}| Parameter | Type | Required | Description |
|---|---|---|---|
nFrames | string | Yes | Total duration: "10", "15", or "25" (must be a string) |
shots | array | Yes | Array of shot objects |
shots[].Scene | string | Yes | Description of the shot (note: capital S) |
shots[].duration | number | Yes | Shot duration in seconds |
aspectRatio | string | No | landscape, portrait, square (default: landscape) |
imageUrls | array | No | Array of image URLs to use as references |
callBackUrl | string | No | Webhook URL for task completion notification |
The total duration of all shots must equal nFrames (within ±0.05 seconds tolerance).
Task Management
Get Task Status
Retrieve the status and result of a generation task.
GET /api/v1/tasks/{taskId}Credits: 0 (Free)
Path Parameters
| Parameter | Type | Description |
|---|---|---|
taskId | string | The task ID returned from a generation request |
Response
{
"code": 200,
"msg": "success",
"data": {
"task_id": "task_abc123",
"status": "completed",
"progress": 100,
"video_url": "https://cdn.example.com/videos/output.mp4",
"thumbnail_url": "https://cdn.example.com/thumbnails/thumb.jpg",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:32:30Z"
}
}Task Status Values
| Status | Description |
|---|---|
pending | Task is queued |
processing | Task is being processed |
completed | Task finished successfully |
failed | Task failed with an error |
Task results are cached for 5 seconds to improve performance.
File Upload
Upload Image
Upload an image for use with image-to-video endpoints.
POST /api/v1/uploadCredits: 0 (Free)
Request
Content-Type: multipart/form-data
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Image file (JPEG, PNG, WebP, GIF) |
Constraints
- Maximum file size: 10 MB
- Allowed formats: JPEG, PNG, WebP, GIF
Response
{
"code": 200,
"msg": "success",
"data": {
"url": "https://cdn.example.com/uploads/image123.jpg",
"expires_at": "2024-01-15T11:00:00Z"
}
}Uploaded images have a temporary URL that expires after 5 minutes. Use them immediately for video generation.
Credits
Get Credit Balance
Retrieve your current API key balance and usage information.
GET /api/v1/creditsCredits: 0 (Free)
Response
{
"code": 200,
"msg": "success",
"data": {
"balance": 4500,
"total_used": 1500,
"total_requests": 45,
"tier": "standard",
"limits": {
"rate_limit": 60,
"max_concurrent": 5,
"daily_limit": 1000
},
"recent_transactions": [
{
"id": "txn_123",
"type": "consume",
"amount": -100,
"balance_after": 4500,
"endpoint": "/api/v1/sora2/text-to-video",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "txn_122",
"type": "recharge",
"amount": 5000,
"balance_after": 4600,
"created_at": "2024-01-14T09:00:00Z"
}
]
}
}Common Response Fields
All endpoints return responses with these common fields:
| Field | Type | Description |
|---|---|---|
code | number | Status code (200 = success) |
msg | string | Status message |
data | object | Response data (on success) |
