Sora Video Generation API: Create and Download Videos

Fhddos exposes an OpenAI-compatible /v1/videos API for generating Sora videos. You submit a task, poll until it finishes, then download the MP4 result. All video operations — creation, status queries, downloads, list retrieval, and remixes — share the same /v1/videos base path so you can route traffic by model group rather than by URL.

Create a Video Task — `POST /v1/videos`

Video generation is asynchronous. A successful POST returns a task object immediately with status: "queued". You then poll GET /v1/videos/{id} until the status reaches success.

cURL — JSON
cURL — Multipart (file upload)

curl -X POST "https://aiapi.fhddos.com/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A drone rises from a beach at golden hour, sweeping across the ocean",
    "seconds": 8,
    "size": "1280x720",
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'

curl -X POST "https://aiapi.fhddos.com/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=A drone rises from a beach at golden hour, sweeping across the ocean" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "input_reference=@/path/to/ref.jpg"

When using a JSON body, input_reference must be a single object — for example {"image_url": "..."} or {"file_id": "file_..."}. Do not pass an array. When using multipart form-data, input_reference is a single file field.

Request Parameters

Parameter	Type	Required	Description
`model`	string	✅	Model name, e.g. `sora-2`, `sora-2-pro`
`prompt`	string	✅	Text description of the video to generate
`seconds`	integer		Duration in seconds. The current API Reference exposes `4`, `8`, and `12`. Refer to your channel’s actual capability
`size`	string		Resolution. Current API Reference lists `720x1280`, `1280x720`, `1024x1792`, `1792x1024`. `sora-2-pro` also supports `1920x1080` and `1080x1920`
`input_reference`	object / file		Reference image — object `{image_url}` or `{file_id}` in JSON; single file in multipart

Creation Response

{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "queued",
  "model": "sora-2",
  "prompt": "A drone rises from a beach at golden hour, sweeping across the ocean",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720"
}

Save the id — you need it to poll for status and to download the finished file.

Poll Task Status — `GET /v1/videos/{id}`

Poll this endpoint periodically until status is success or failed.

curl "https://aiapi.fhddos.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"

Status Progression

Status	Meaning
`queued`	Task created and waiting for a processing slot
`processing`	Video is actively being generated
`success`	Generation complete — ready to download
`failed`	Generation failed — check `error.code` and `error.message`

In-Progress Response

{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "processing",
  "model": "sora-2",
  "prompt": "A drone rises from a beach at golden hour, sweeping across the ocean",
  "progress": 45,
  "seconds": "8",
  "size": "1280x720"
}

Completed Response

{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "completed_at": 1762789891,
  "expires_at": 1762793491,
  "status": "success",
  "model": "sora-2",
  "prompt": "A drone rises from a beach at golden hour, sweeping across the ocean",
  "progress": 100,
  "seconds": "8",
  "size": "1280x720"
}

Field	Description
`progress`	Generation progress from 0 to 100
`completed_at`	Unix timestamp of completion (present only on `success`)
`expires_at`	Unix timestamp after which the video is no longer available (present only on `success`)

Videos expire relatively quickly after completion. Download and store the file locally as soon as your polling detects status: "success".

Download a Video — `GET /v1/videos/{id}/content`

Once the task status is success, download the MP4 file:

curl -L "https://aiapi.fhddos.com/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  --output "$VIDEO_ID.mp4"

Always include -L to follow redirects — the video file may be served from a CDN with a redirect chain. Downloading does not consume any additional quota; you can download the same video multiple times.

The endpoint returns the raw video binary as video/mp4. A 404 means either the task ID is wrong or the video has not yet completed (check status first). A 400 means the video is not yet ready.

List All Video Tasks — `GET /v1/videos`

Retrieve all video tasks associated with your token, with pagination support:

curl "https://aiapi.fhddos.com/v1/videos?limit=10&order=desc" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters

Parameter	Description
`after`	Pagination cursor — pass the `id` of the last item from the previous page
`limit`	Maximum number of tasks to return
`order`	Sort direction: `asc` or `desc`

Response

{
  "object": "list",
  "data": [
    {
      "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
      "object": "video",
      "created_at": 1762789802,
      "status": "success",
      "model": "sora-2",
      "prompt": "A drone rises from a beach at golden hour, sweeping across the ocean",
      "progress": 100,
      "seconds": "8",
      "size": "1280x720"
    }
  ]
}

Video Remix — `POST /v1/videos/{id}/remix`

Remix lets you create a derivative video from an existing completed task by supplying a new prompt. The remix inherits the original video’s resolution and duration while applying your new instructions.

curl -X POST "https://aiapi.fhddos.com/v1/videos/$VIDEO_ID/remix" \
  -H "Authorization: Bearer $TOKEN" \
  -F "prompt=Add a sunset filter and a brand logo at the end"

Request Parameters

Parameter	Location	Description
`video_id`	Path	ID of the original completed video task
`prompt`	Body	Remix instruction, up to 1000 characters

Remix Response

{
  "id": "video_def456789abc012345678901234567890123456789",
  "object": "video",
  "created_at": 1762789902,
  "status": "queued",
  "model": "sora-2",
  "prompt": "Add a sunset filter and a brand logo at the end",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720",
  "remixed_from_video_id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737"
}

The remixed_from_video_id field identifies the source task. Poll and download the remix result exactly as you would any other video task.

The source video must be in a terminal success state (status: "success") before you can remix it. Remix tasks consume the same quota as creating a new video.

Common Remix Use Cases

Add Branding

Overlay a logo or title card at the start or end of a finished video.

Style Adjustment

Change colour grading, apply a cinematic filter, or shift the artistic style.

Detail Modification

Adjust specific objects or elements in the scene using natural language.

Scene Extension

Add new scenes before or after the original content.

Full Remix Workflow (Shell Script)

# 1. Create the base video
VIDEO_ID=$(curl -s -X POST "https://aiapi.fhddos.com/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=A drone rises from a beach at golden hour" \
  | jq -r '.id')

# 2. Poll until complete
while true; do
  STATUS=$(curl -s "https://aiapi.fhddos.com/v1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  [ "$STATUS" = "success" ] && break
  echo "Status: $STATUS — waiting…"
  sleep 10
done

# 3. Create the remix
REMIX_ID=$(curl -s -X POST "https://aiapi.fhddos.com/v1/videos/$VIDEO_ID/remix" \
  -H "Authorization: Bearer $TOKEN" \
  -F "prompt=Add a warm sunset colour grade" \
  | jq -r '.id')

# 4. Download the remix
curl -L "https://aiapi.fhddos.com/v1/videos/$REMIX_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  --output "remix_$REMIX_ID.mp4"

Video Routing and Cost Optimisation

Fhddos routes Sora requests through two channel groups without changing the public /v1/videos endpoint. You control which group a token uses via the pricing_group setting in the console.

Dimension	Official Group	Economy Group
Public path	`/v1/videos`	`/v1/videos`
`seconds` values	Follows official OpenAI docs	May include non-standard slots (e.g. `10`, `15`, `25`)
`size` values	Follows official OpenAI docs	May accept shorthand aliases like `16x9`
`input_reference`	Official multipart / JSON object semantics	Some proxy channels accept looser inputs
Character fields	Not part of the public official contract	Some channels support `character_url`, `character_timestamps`
OpenAI compatibility promise	✅ Applies	❌ Does not apply

If your application must guarantee OpenAI official compatibility, set the token’s pricing_group to your official group and set upgrade_policy: none to prevent automatic fallback to economy channels. Enable ModelRoutingStrictGroupEnabled in your system configuration.

A conservative token configuration:

{
  "pricing_group": "pro",
  "upgrade_policy": "none"
}

The Sora Characters API (OpenAI’s official /v1/videos/characters feature) is a distinct capability. Fhddos’s current character-related entry points are not equivalent to the official Characters API and should not be described as such. See the official OpenAI documentation for Characters API details.

​Create a Video Task — POST /v1/videos

​Request Parameters

​Creation Response

​Poll Task Status — GET /v1/videos/{id}

​Status Progression

​In-Progress Response

​Completed Response

​Download a Video — GET /v1/videos/{id}/content

​List All Video Tasks — GET /v1/videos

​Query Parameters

​Response

​Video Remix — POST /v1/videos/{id}/remix

​Request Parameters

​Remix Response

​Common Remix Use Cases

Add Branding

Style Adjustment

Detail Modification

Scene Extension

​Full Remix Workflow (Shell Script)

​Video Routing and Cost Optimisation

Create a Video Task — `POST /v1/videos`

Request Parameters

Creation Response

Poll Task Status — `GET /v1/videos/{id}`

Status Progression

In-Progress Response

Completed Response

Download a Video — `GET /v1/videos/{id}/content`

List All Video Tasks — `GET /v1/videos`

Query Parameters

Response

Video Remix — `POST /v1/videos/{id}/remix`

Request Parameters

Remix Response

Common Remix Use Cases

Full Remix Workflow (Shell Script)

Video Routing and Cost Optimisation