JUHE API Marketplace

Create Cinematic Clips from Images with Sora 2 API (JuheAPI Guide)

6 min read

Why Sora 2 for Image-to-Video

Developers and startups increasingly need fast, controllable motion generation for product demos, ads, and social clips. Sora 2 Pro on Wisdom Gate’s JuheAPI turns stills into smooth cinematic sequences with scene cohesion, extended durations, and practical controls via simple HTTP calls. If you’ve tried text-only prompts before, image-to-video lets you anchor a scene with a photo and add camera moves, environmental motion, and timed pacing—ideal for design teams and marketing.

How the Workflow Fits Your Stack

Sora 2 runs tasks asynchronously. You submit a request (multipart/form-data) with the model, prompt, duration, and optionally one or more images. JuheAPI returns a task ID immediately, so your service isn’t blocked while generation happens. You poll the task or view progress on the dashboard. When complete, you download the result, store it in your own bucket, and move on.

  • Submit: POST to /v1/videos with model=sora-2-pro, prompt, seconds, and image files
  • Track: GET the task by ID or watch the Wisdom Gate dashboard
  • Retrieve: Download the rendered video and archive it (logs retained ~7 days)

Getting Started with Sora 2 Pro

Step 1: Sign Up and Get API Key

  • Visit Wisdom Gate’s dashboard, create your account, and generate an API key.
  • The dashboard shows active tasks, progress, and finished assets.

Step 2: Model Selection

  • Choose sora-2-pro for the most advanced features.
  • Expect smoother motion, better scene cohesion, extended durations compared to base models.

Step 3: Make Your First Request

Here’s a minimal call to render a serene lake scene using only text-to-motion.

curl -X POST "https://wisdom-gate.juheapi.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="sora-2-pro" \
  -F prompt="A serene lake surrounded by mountains at sunset" \
  -F seconds="25"

Step 4: Check Progress

Sora 2 executes asynchronously. You can poll by task ID:

curl -X GET "https://wisdom-gate.juheapi.com/v1/videos/{task_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Alternatively, watch progress and download results from the dashboard:

From Stills to Cinematic Motion

The core of image-to-video is uploading one or more images as anchors for composition. Sora 2 Pro builds motion cues around your stills—camera pans, parallax, environmental movement (water, foliage), and stylistic timing.

Input Files: How to Attach Images

Send multipart/form-data with your prompt and one or more image fields. Many HTTP clients support repeating the same field name for multiple files.

  • Single image: add one image field
  • Multiple images: repeat the image field to supply a sequence
  • Duration: control clip length via seconds

Note: APIs can evolve. If your account expects images[] instead of image, use the array-style field names in your form. If you receive a 400 mentioning a missing images field, retry with images[] entries.

Single Image: Cinematic Pan and Environmental Motion

Start with one photo and let Sora 2 add tasteful camera movement.

curl -X POST "https://wisdom-gate.juheapi.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="sora-2-pro" \
  -F prompt="Subtle dolly-in over a tranquil lakeside, gentle ripples, warm sunset lens flare, cinematic color" \
  -F seconds="12" \
  -F image=@./lake.jpg

Tips:

  • Keep prompts short but specific: motion type (pan, tilt, dolly), atmosphere (warm, moody), and elements (ripples, foliage sway).
  • Start with 8–12 seconds to test pacing; extend once you like the motion style.

Multi-Image Storyboard: Smooth Cut or Morph

Use 2–4 images to suggest a mini-sequence. Sora 2 can interpolate or smoothly cut between frames while keeping a cohesive look.

curl -X POST "https://wisdom-gate.juheapi.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="sora-2-pro" \
  -F prompt="Calm travel montage: wide lake → closer shore → forest path. Gentle crossfade, soft camera drift, filmic grain." \
  -F seconds="18" \
  -F image=@./lake-wide.jpg \
  -F image=@./shore-close.jpg \
  -F image=@./forest-path.jpg

Guidance:

  • Keep visual continuity (lighting, color temperature) across images for seamless transitions.
  • Longer montages cost more time; 15–25 seconds is a practical balance for social clips.

Duration and Pacing Controls

  • seconds: total clip length; longer requires more processing
  • Try increments (8, 12, 18, 25) and review pacing
  • Short clips often benefit from more pronounced camera motion; lengthen for subtlety

Text-to-Motion Prompting

Text strongly influences motion style. Even with images, prompts clarify camera behavior and environmental dynamics.

Prompt examples:

  • “Slow tilt up from water to sky, gentle wind ripples, warm golden-hour glow, cinematic grade”
  • “Parallax pan across pine trees, subtle film grain, delicate light flares, serene mood”
  • “Dramatic dolly-forward, soft bokeh, mist rolling across lake, cohesive color palette”

Checking Status and Downloading Results

You can poll the task and read its status. The dashboard shows queued, running, and completed states and exposes download controls.

  • Poll via GET /v1/videos/{task_id}
  • If your team automates downloads, poll with exponential backoff and stop after completion or failure
  • Download early: logs and assets are retained for a limited window (typically ~7 days); archive to your storage

Example polling loop (shell-style pseudocode):

TASK_ID=your-task-id
API_KEY=your-api-key
STATUS="queued"
while [ "$STATUS" != "completed" ] && [ "$STATUS" != "failed" ]; do
  RESP=$(curl -s -H "Authorization: Bearer $API_KEY" \
    "https://wisdom-gate.juheapi.com/v1/videos/$TASK_ID")
  STATUS=$(echo "$RESP" | jq -r '.status // "queued"')
  echo "Status: $STATUS"
  sleep 6
done

Best Practices for Stable Video Generation

  • Prompt precision: describe subject, environment, and atmosphere clearly
  • Test durations: longer clips need more compute; tune for your goal
  • Download early: archive assets to your own bucket (retention ~7 days)
  • Visual coherence: use images with compatible lighting, lens, and color
  • Motion moderation: start subtle; dial up intensity after review
  • Iterative refinement: lock one variable at a time (prompt, duration, image set)
  • Asset readiness: high-resolution source images yield better parallax
  • Reproducibility: keep a prompt and parameter log per render

Error Handling and Troubleshooting

Common issues and quick fixes:

  • 401 Unauthorized: wrong or expired API key; regenerate from dashboard
  • 400 Bad Request: missing fields (model, prompt, seconds, or images); verify names
  • Rate limit exceeded: spread requests and add a queue; back off exponentially
  • Timeouts: the task is still running; rely on polling rather than long, blocking calls
  • Asset not found (download): the retention window passed; re-render or archive immediately next time

Troubleshooting checklist:

  • Confirm model="sora-2-pro"
  • Use Content-Type multipart/form-data (not application/json)
  • If images produce errors, try images[] field naming
  • Validate seconds (integer string, e.g., "18")
  • Reduce request size if you attach many large images; try two, then add more

Production Integration Patterns

Make generation resilient and cost-aware.

Queueing and Concurrency

  • Use a job queue (e.g., sidekiq, Celery, SQS) to control throughput
  • Batch similar jobs to warm caches (prompts with similar scenes)
  • Cap concurrent renders to avoid rate-limit hits

Backoff and Retries

  • Poll every 6–12 seconds initially; slow down after 1–2 minutes
  • Retry transient 5xx errors with jitter (e.g., 3 attempts)

Storage and CDN

  • Save outputs immediately to S3