--- title: "Sora 2 Pro JSON Prompt — Video API Newcomer Guide" description: "Beginner-friendly Sora 2 Pro JSON prompt guide: every field explained, 3 copy-paste examples, and when to use it vs alternatives. 56 credits on AI Content Drop." canonical: "https://aicontentdrop.com/blog/sora-2-pro-json-prompt-guide" source: "https://aicontentdrop.com/blog/sora-2-pro-json-prompt-guide" --- ## What This Guide Does This guide explains every field in a Sora 2 Pro JSON prompt — the structured text request you send to OpenAI's most capable video generation model via the official OpenAI API. By the end you'll be able to send your first request to Sora 2 Pro and understand every field in the JSON, even if you've never called an AI model API before. We'll define the terminology you need, show you the full request body you can copy and run today, then break down every field one by one. We'll cover three ready-to-use prompt bodies for different video styles, the most common mistakes newcomers make with Sora 2 Pro specifically, and a plain cost breakdown so you know what to budget. No background in coding is required — if you can read and copy text, you can follow along. ## What Is Sora 2 Pro? Sora 2 Pro is a text-to-video AI model made by OpenAI. You write a text description — called a **prompt** — and it generates a short video clip. It sits at the top of the Sora model family, above the base Sora 2 (45 credits) and the older Sora (56 credits). Sora 2 Pro is best at creative, narrative, and fantastical scenes where you need the model to interpret a story-driven description and produce coherent motion across the whole clip. It handles imaginative prompts — a character running through a dreamlike forest, a product dissolving into light, a moody noir detective scene — better than most models in its class. The one thing it can't do well is strict photorealistic talking-head UGC; for that, models trained on human footage (like Veo 3.1 or Kling 3.0) tend to produce more natural-looking results. There is also a separate Storyboard variant (`sora-2-pro-storyboard`, 84 credits) for multi-panel storyboard outputs — that is a different use case and is not covered here. Sora 2 Pro is available via OpenAI's official API using the model identifier `sora-2-pro`. On AI Content Drop, each Sora 2 Pro generation costs **56 credits** — billed only after your video generates successfully (post-deduct billing means you don't pay if the generation fails). AI Content Drop handles the API call for you — but if you want to call OpenAI directly, here's the official shape. For a side-by-side look at how it compares to Kling, see the [Sora 2 vs Kling 3 comparison](https://aicontentdrop.com/blog/sora-2-vs-kling-3), or read the full [Sora AI model review](https://aicontentdrop.com/blog/sora-ai-review). ## The Complete JSON Prompt Below is a full Sora 2 Pro API request body you can copy, paste, and send right now using the official OpenAI Videos API. This is **JSON** — JavaScript Object Notation, a text format APIs use to send structured requests. Each line is a key–value pair; together they tell the model exactly what video to make. ``` { "model": "sora-2-pro", "prompt": "A lone explorer in a worn leather jacket steps out of a fog-covered forest onto a clifftop at dawn, slow dolly forward from wide to medium shot, golden sunrise light breaking through clouds, cinematic epic fantasy aesthetic, film grain", "size": "1280x720", "seconds": "8" } ``` At a glance: `model` selects the exact OpenAI video model to use; `prompt` is your description of the scene; `size` sets the pixel dimensions of the output frame; and `seconds` controls how long the clip runs. ## Field-by-Field Breakdown Let's go through every field. For each one you'll see its type, whether it's required, what happens if you leave it out, and a quick example showing good usage versus a common mistake. ### model **Type:** string | **Required:** yes Selects which OpenAI video model handles your request. Use `"sora-2-pro"` for the highest-quality tier. The standard tier uses `"sora-2"` (fewer credits, slightly lower fidelity on complex prompts). Always spell the model ID exactly — the API is case-sensitive. **Good:** `"sora-2-pro"` when you need the highest cinematic quality and are prepared to spend 56 credits per clip. **Mistake:** Sending `"sora2pro"` or `"Sora-2-Pro"` — these do not match a valid model ID and will return a validation error. ### prompt **Type:** string | **Required:** yes This is the most important field. It's a plain-English description of the video you want. The model reads your prompt and generates a clip that matches. A good Sora 2 Pro prompt covers four things: what's in the frame (subject), what's happening (action), how the camera is positioned (framing), and the visual style. Sora 2 Pro responds particularly well to narrative language — describing a scene as if you were writing a short screenplay tends to produce better motion than a flat list of adjectives. **Good:** "A confident founder in a navy blazer walks toward the camera through a rain-soaked city street at night, slow tracking shot at street level, neon signs reflecting in the puddles, cinematic storytelling style" **Weak:** "A founder walking" — too vague; the model will fill in every detail randomly and produce something generic. Keep prompts between 30 and 200 words. Under 30 words the model lacks enough detail; over 200 words it starts ignoring parts of your description. ### size **Type:** string (enum) | **Required:** no | **Default:** `"1280x720"` Sets the pixel dimensions of the output video. The value is expressed as `widthxheight` — for example `"1280x720"` is standard landscape HD, and `"720x1280"` is portrait (vertical for TikTok and Instagram Reels). Always match the size to where the video will be shown — the model uses the frame dimensions to decide how much of the scene to render. **Good:** `"720x1280"` when your prompt describes a full-body character or a tall product shot destined for TikTok. **Mistake:** Using `"1280x720"` for a "full-body fashion walk to camera" — the subject will appear far away and the extra horizontal space is just empty background. Match the size to the subject. ### seconds **Type:** string (enum) | **Required:** no | **Default:** `"8"` How many seconds long the video should be. Note that this field is a *string*, not a number — pass `"4"`, `"8"`, or `"12"` in quotes, not as bare integers. Most social ad use cases work at 8 seconds — it's enough for one clear scene with a little room for motion to develop. Use `"12"` when you need a longer reveal, a slow atmospheric sequence, or a multi-beat narrative. Use `"4"` for a very short, punchy hook. **Good:** `"8"` for a product close-up or a punchy hook scene. `"12"` for a dreamlike establishing sequence or a narrative arc with a beginning and end. **Mistake:** Sending `8` (an integer without quotes) — the API expects a string for this field, so pass `"8"`. Sending an unsupported value like `"10"` will return a validation error. Valid values are`"4"`, `"8"`, and `"12"` only. ### input_reference **Type:** string (URL or file ID) or `null` | **Required:** no | **Default:** `null` An optional reference image for image-to-video generation. When provided, the model uses the image as the first frame (or a visual anchor) and animates from it according to your prompt. You can pass a publicly accessible HTTPS image URL or an OpenAI file ID (from a prior`POST /v1/files` upload). Leave this as `null` or omit it entirely for pure text-to-video. **Good:** Pass a product image URL when you want the model to animate your actual product rather than generating one from scratch. This is useful for e-commerce ads where brand accuracy matters. **Mistake:** Passing a local file path like `"/images/shoe.jpg"` — the API cannot reach your local filesystem. Upload to a public URL or use the Files API first. *Note: the exact field name and behavior for image-to-video may evolve — consult the latest OpenAI docs at [platform.openai.com/docs/api-reference/videos](https://platform.openai.com/docs/api-reference/videos) before building production integrations.* ## Allowed Values Reference Table This table lists every parameter Sora 2 Pro accepts via the OpenAI Videos API. Bookmark it — when you get an "invalid parameter" error, this is the first place to check. | Field | Allowed values | Notes | | --- | --- | --- | | `model` | `"sora-2-pro"`, `"sora-2"` | Required. Use `sora-2-pro` for maximum quality. | | `prompt` | Any string, 1–2000 chars | Required. Sweet spot: 30–200 words. | | `size` | `"1280x720"`, `"720x1280"`, `"1024x1792"`, `"1792x1024"` | Default is `"1280x720"`. Width × height in pixels. | | `seconds` | `"4"`, `"8"`, `"12"` | String, not integer. Default is `"8"`. | | `input_reference` | HTTPS image URL, OpenAI file ID, or `null` | Optional. Enables image-to-video. Omit for text-to-video. | One thing you'll notice: Sora 2 Pro does *not* expose a `negativePrompt` field. Unlike some other models (such as Veo 3.1), Sora 2 Pro handles negative intent through your main prompt — describe what you want, not what you don't want. If you need to steer away from something, phrase it positively: "clean background, no text" works better as part of the main prompt than as a separate exclusion list. ## 3 Working Copy-Paste Examples ### Example 1: E-commerce — Sneaker on a Pedestal ``` { "model": "sora-2-pro", "prompt": "White limited-edition sneaker slowly rotating on a glowing white pedestal, 360-degree orbit camera movement, soft studio spotlight with a deep charcoal-to-black gradient backdrop, cinematic product reveal aesthetic, hyper-clean minimal composition", "size": "1024x1792", "seconds": "8" } ``` Portrait format (`1024x1792`) sits naturally on an Instagram grid or a product carousel. The orbit camera shows all angles of the shoe across the clip without rushing. Sora 2 Pro handles the smooth rotation well because it's a simple, single-action prompt with a clear subject and clear framing instruction. Expect a polished, clean output — suitable for an e-commerce listing or a paid social asset. The deep backdrop helps the white sneaker pop. ### Example 2: Portrait — Founder Talking to Camera ``` { "model": "sora-2-pro", "prompt": "A confident entrepreneur in their early 30s wearing a crisp white shirt speaks directly to camera in a bright minimal studio, static medium close-up with subtle rack focus to background, soft diffused key light from the left, cinematic narrative testimonial style", "size": "720x1280", "seconds": "12" } ``` Portrait size (`720x1280`) puts the speaker front and centre for TikTok or Reels. Twelve seconds gives enough run-time for a full spoken hook. The rack focus adds a professional look without needing camera movement. One thing to be aware of: Sora 2 Pro has stricter content moderation than most models — prompts that reference real named individuals, brand logos, or anything that could be mistaken for a deepfake will be rejected. Using generic descriptions ("an entrepreneur" rather than a real name) keeps you well clear of the policy line. ### Example 3: Cinematic — Moody Urban Street Scene ``` { "model": "sora-2-pro", "prompt": "A rain-soaked cobblestone alley in a European city at midnight, single streetlamp casting a warm amber pool of light onto the wet stones, slow forward dolly from wide establishing shot pushing toward a glowing doorway in the distance, volumetric mist catching the lamplight, film noir aesthetic, 35mm grain", "size": "1280x720", "seconds": "12" } ``` Landscape size (`1280x720`) suits the wide-to-tight dolly described in the prompt. Twelve seconds lets the camera movement complete without feeling rushed. The volumetric mist phrase reliably activates atmospheric depth on Sora 2 Pro. This style works as brand B-roll, the opening shot of a cinematic ad, or a mood piece for a fashion or lifestyle campaign. Expect deep shadows and warm lamplight reflections — exactly what the prompt asks for. ## How to Send the Request An **API endpoint** is a URL your code sends a request to — think of it as a mailbox address where the AI model lives. For Sora 2 Pro, the official OpenAI Videos API uses a two-step async flow. First, you **POST** your job to `https://api.openai.com/v1/videos` and receive a video ID immediately. Then you **poll** — repeatedly GET `https://api.openai.com/v1/videos/{video_id}` every few seconds until `status` changes to `"completed"`. Finally, you download the finished file from `https://api.openai.com/v1/videos/{video_id}/content`. You will need an **OpenAI API key** — get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). Important: Sora is a gated model — not all OpenAI accounts have access. If you receive a `403` response, your organisation may need to apply for Sora access through OpenAI's platform. Once access is granted, your API key works immediately. Here is a curl example — Step 1, submit the job (run this in your terminal): ``` curl -X POST https://api.openai.com/v1/videos \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "sora-2-pro", "prompt": "A lone explorer steps onto a clifftop at dawn, slow dolly forward, golden sunrise light, cinematic epic fantasy aesthetic", "size": "1280x720", "seconds": "8" }' ``` Step 2 — poll for the result (replace `VIDEO_ID` with the `id` from the response above): ``` curl https://api.openai.com/v1/videos/VIDEO_ID \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` Step 3 — download the finished MP4 once `status` is `"completed"`: ``` curl https://api.openai.com/v1/videos/VIDEO_ID/content \ -H "Authorization: Bearer $OPENAI_API_KEY" \ --output my-video.mp4 ``` Here is the same full flow in JavaScript (works in Node.js or a browser): ``` // Step 1 — submit the job const submit = await fetch("https://api.openai.com/v1/videos", { method: "POST", headers: { "Authorization": "Bearer " + process.env.OPENAI_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ model: "sora-2-pro", prompt: "A lone explorer steps onto a clifftop at dawn, slow dolly forward, golden sunrise light, cinematic epic fantasy aesthetic", size: "1280x720", seconds: "8" }) }); const job = await submit.json(); const videoId = job.id; // save this // Step 2 — poll every 5 seconds until complete let result; while (true) { await new Promise(r => setTimeout(r, 5000)); const poll = await fetch(`https://api.openai.com/v1/videos/${videoId}`, { headers: { "Authorization": "Bearer " + process.env.OPENAI_API_KEY } }); result = await poll.json(); if (result.status === "completed" || result.status === "failed") break; } // Step 3 — download the MP4 if (result.status === "completed") { const download = await fetch(`https://api.openai.com/v1/videos/${videoId}/content`, { headers: { "Authorization": "Bearer " + process.env.OPENAI_API_KEY } }); const buffer = await download.arrayBuffer(); // save buffer to file... } ``` Or skip the API key entirely — paste your prompt into the [Chat-to-Ads Studio](https://aicontentdrop.com/) or the [video generation page](https://aicontentdrop.com/best-ai-video-generator) and we'll handle the request for you. No API key needed — just pick Sora 2 Pro from the model list, write your prompt, and click generate. ## What the Response Looks Like Sora 2 Pro is an **async** model — it doesn't return the finished video instantly. Instead it returns a video object with a unique `id` and an initial status of `"queued"` or `"processing"`. This process is called **polling**: you ask "is it done yet?" every few seconds until the `status` field changes to `"completed"`. Initial response right after you POST your prompt: ``` { "id": "video_abc123xyz789", "object": "video", "status": "queued", "created_at": 1746268934, "model": "sora-2-pro", "prompt": "A lone explorer steps onto a clifftop at dawn..." } ``` Save the `id`. Then GET the status endpoint every 5 seconds: `GET https://api.openai.com/v1/videos/{video_id}` When the video is ready, the `status` field changes and a `completed_at` timestamp appears: ``` { "id": "video_abc123xyz789", "object": "video", "status": "completed", "created_at": 1746268934, "completed_at": 1746269052, "model": "sora-2-pro", "prompt": "A lone explorer steps onto a clifftop at dawn...", "size": "1280x720", "seconds": "8" } ``` The `status` field moves through: `"queued"` → `"processing"` → `"completed"` (or `"failed"` if something went wrong). Once status is `"completed"`, download the MP4 bytes by calling `GET https://api.openai.com/v1/videos/{video_id}/content`. You can also append `?variant=thumbnail` to fetch a preview image. Sora 2 Pro generations typically complete within 60–120 seconds depending on prompt complexity and server load. If`status` is `"failed"`, check the `error` field on the object for the reason. ## Common Errors and Fixes - Error: 400 invalid_value mentioning size Meaning: You sent a size value Sora 2 Pro doesn't support — for example "1920x1080" or a ratio-style value like "16:9" . Fix: Use only "1280x720" , "720x1280" , "1024x1792" , or "1792x1024" . For portrait content, pick "720x1280" and crop afterward if needed. - Error: 400 invalid_value mentioning seconds Meaning: You sent a duration value that is either the wrong type (integer instead of string) or an unsupported length. The most common version is passing 10 — which works on some other models but not Sora 2 Pro. Fix: Use only the string values "4" , "8" , or "12" — always in quotes. - Error: 400 missing_required_parameter: prompt Meaning: You forgot to include the prompt key in your JSON body, or its value is an empty string. Fix: Make sure your JSON has a "prompt" key with a non-empty string value. It's one of the two required fields (along with model ). - Error: 400 content_policy_violation Meaning: Your prompt triggered Sora 2 Pro's content moderation. Sora 2 Pro has stricter moderation than most other video models — it is especially sensitive to prompts that reference real named individuals (which could imply a deepfake), brand logos, graphic violence, or explicit content. Newcomers hit this often when they try to generate a video of a real public figure. Fix: Replace real names with generic descriptions ("a tech founder" instead of a specific person's name). Remove any graphic language. Avoid referencing trademarked brand names in the visual description. Rephrasing to focus on scene and style rather than identity usually clears the filter. - Error: 401 invalid_api_key Meaning: Your API key is missing, wrong, or expired. Fix: Check that your Authorization header says Bearer YOUR_KEY (capital B, one space before your key, no extra characters). Copy the key fresh from platform.openai.com/api-keys — trailing spaces are the most common cause. - Error: 403 model_not_found or 403 access_denied Meaning: Sora is gated — your OpenAI organisation has not been granted access to the Sora model family yet. Fix: Apply for Sora access through your OpenAI platform account. Once approved, your existing API key will work without changes. In the meantime, you can generate Sora videos on AI Content Drop without managing API access yourself. - Error: 429 rate_limit_exceeded Meaning: You've hit the rate limit for your OpenAI account tier. Fix: Wait a moment before retrying. Sora generation jobs are compute-intensive — OpenAI enforces per-minute and per-day limits depending on your usage tier. On AI Content Drop, each Sora 2 Pro generation costs 56 credits. - Error: status: "failed" in the polling response Meaning: The model attempted generation but couldn't complete it. This is rare and usually a transient server issue. Fix: Retry the request. If it fails multiple times in a row, check the OpenAI status page at status.openai.com . You are not charged for failed generations on AI Content Drop (post-deduct billing — credits only leave your balance on a successful output). ## Sora 2 Pro vs Alternatives — When to Use Which Not every video job calls for Sora 2 Pro. Here's a plain comparison to help you pick the right model. You can browse all available models on the [model marketplace](https://aicontentdrop.com/marketplace). | Use this if… | Model | Credits | | --- | --- | --- | | You need creative, narrative, or fantastical scenes — brand films, cinematic intros, imaginative product reveals, or anything where the model needs to interpret a story | Sora 2 Pro | 56 | | You want photorealistic commercial footage — talking-head UGC, lifestyle ads, product on shelf — where physical accuracy and human faces matter. See the [Kling vs Sora comparison](https://aicontentdrop.com/blog/kling-vs-sora-comparison) for a detailed breakdown | Kling 3.0 | 22 | | You want sharper realism on a tighter budget and your scene is grounded in real-world settings with natural lighting | Veo 3.1 | 26 | The short version: Sora 2 Pro is the right choice when your prompt is cinematic, story-driven, or imaginative. If your prompt reads more like a product brief or a UGC talking-head script, you'll likely get better results — and spend fewer credits — on Kling 3.0 or Veo 3.1. ## Cost Math for Newcomers Let's work through a real example so you know what to budget before you start. Say you want to test **10 cinematic ad variants** for a brand launch — different scenes, different moods, different camera moves. Each Sora 2 Pro generation costs **56 credits**. Ten variants = **560 credits**. On the Starter plan ($19/month) you get enough credits to cover a decent test batch. On the Professional plan ($49/month) you have room for multiple full campaign sets per month. The key thing to remember: you only pay on a successful generation (post-deduct billing) — if a video fails due to a server error or content policy block, your credits are not deducted. To keep costs down while you're learning, start with shorter prompts at `"4"`-second duration. Once you've found a prompt structure that works, switch to `"12"` seconds for the final deliverables. That discipline alone saves roughly 30–40% of your credit spend on a typical exploration round. ## Glossary **Prompt** The text description you write to tell an AI model what video to generate. It goes in the `prompt` field of your JSON request. **JSON (JavaScript Object Notation)** A plain-text format for sending structured data to APIs. It uses curly braces `{}`, key–value pairs, and commas. **API request** A message your code sends to a remote service (like a video model) asking it to do something. The request includes a URL, a method (POST or GET), and usually a JSON body. **Endpoint** The specific URL you send your request to. For Sora 2 Pro, the submission endpoint is `https://api.openai.com/v1/videos` and the polling endpoint is `https://api.openai.com/v1/videos/{video_id}`. **video_id** A unique identifier (e.g. `video_abc123xyz789`) the OpenAI API returns when you submit a generation job. You use it to poll for status and to download the finished file. **Polling** The process of repeatedly asking the API "is the video ready yet?" by making GET requests to the status endpoint every few seconds until `status` changes to `"completed"`. **Aspect ratio / size** The width-to-height proportion of the video frame, expressed here as pixel dimensions. `1280x720` is standard landscape; `720x1280` is vertical (mobile-first); `1024x1792` is tall portrait. **Post-deduct billing** A billing model where credits are only charged after a generation completes successfully. If the generation fails, you keep your credits. ## FAQ ### Can I just use the chat instead of writing JSON? Yes. The [Chat-to-Ads Studio](https://aicontentdrop.com/) lets you describe your video in plain English and handles the JSON formatting for you. Writing raw JSON gives you more precise control over parameters like size and duration — but for most newcomers, the chat interface is faster and less error-prone as a starting point. ### What if I get a 401 error? A 401 means your API key is missing or wrong. Check that your `Authorization` header is spelled correctly and reads `Bearer YOUR_KEY` (capital B, one space before your key, no extra characters). Copy the key fresh from [platform.openai.com/api-keys](https://platform.openai.com/api-keys) — trailing spaces are the single most common cause of 401 errors. ### How do I get an aspect ratio not in the list? You can't — Sora 2 Pro only supports the four sizes in the table above. If you need a different ratio (like 4:5 for an Instagram portrait ad), generate in `"720x1280"` and crop the top and bottom in a video editor afterward. Most editing tools let you do this in under a minute. ### Does Sora 2 Pro support audio generation? Sora 2 Pro generates video only — no audio track is included in the output. If you need a voiceover or background music, generate the video first and add audio separately using your editing tool or a TTS service. The [video generation page](https://aicontentdrop.com/best-ai-video-generator) on AI Content Drop lets you combine the video output with audio in one workflow. Note that the Sora 2 Pro Storyboard variant (`sora-2-pro-storyboard`) is a separate model for multi-panel storyboard outputs and costs 84 credits — it is not the same as the standard Sora 2 Pro covered in this guide.