Building a Video Upload Endpoint with Cursor or Claude Code

Knowing that AIOZ Stream publishes llms.txt files is one thing. Actually pointing Cursor or Claude Code at them and getting working code out the other end is a different, more practical question. This walks through doing that for a specific, common task: an upload endpoint that creates a video object, uploads the file, and returns something the caller can poll for status.

TL;DR:

• You need an API key (an only_upload key is enough for this task) and the relevant llms.txt section files, not the whole API surface at once.
• In Cursor, drop the section files into the project and @-mention only the ones relevant to the current task.
• In Claude Code, reference the files directly in your prompt or keep them in the project directory where they get picked up as context.
• The generated code should use video.create() then upload, not skip straight to uploading, and should poll for a "done" status rather than assuming the video is ready immediately.
• Check the output against the real docs before shipping it, the same disclaimer AIOZ Stream's own llms.txt file carries.

What to have ready before you start

Two things: an API key with the right scope, and the right files. For an upload endpoint specifically, an only_upload key is enough, there's no reason to hand a coding assistant credentials that can also delete videos or manage other keys. For files, pulling in every section file at once defeats the point of having them split up; for this task, media-video.md and, if you want status polling to trigger a webhook instead of a manual check, webhooks.md are the ones that matter. Which of those two approaches you actually want is worth deciding before you prompt for either: polling with getDetail() is simpler to implement and reason about for a low-volume endpoint, while a webhook avoids the wasted requests of polling something that isn't done yet, at the cost of needing a handler that's reachable from AIOZ's servers and, per standard webhook practice, idempotent against duplicate delivery.

Setting up in Cursor

Save the section files you need into the project, then reference them directly in chat with @media-video.md (and @webhooks.md if you're including that). This keeps the context window focused on exactly what the current task needs instead of loading the full API surface for a change that only touches one resource. If a later task needs playlists or analytics instead, swap in those files rather than keeping everything attached by default. Cursor's own documentation on @-mentions confirms this is the intended pattern generally, not just something that happens to work for AIOZ Stream's files specifically: reference exactly what's relevant per message rather than relying on everything in the project being implicitly in scope.

Setting up in Claude Code

Claude Code picks up files in the project directory as available context, and you can also reference a specific file directly in a prompt, for example asking it to read media-video.md before writing an upload handler. Keeping the section files in a dedicated docs folder rather than scattered through the codebase makes it easier to reference exactly the right one without also pulling in unrelated project files that happen to share a directory. A folder like docs/aioz-reference/ with just the section files you're actively using also makes it obvious later which reference files a given task actually depended on, useful if you come back to the same integration weeks later and need to remember what it was built against.

A worked prompt

A reasonable prompt for the upload-endpoint task looks like: "Using media-video.md, write a Node.js Express endpoint that creates a video object, uploads the given file, and returns an endpoint the caller can poll for encoding status." A correct implementation, based on what the reference files actually document, creates the video object first, uploads the file second, and exposes status by calling video.getDetail(id) rather than assuming the video is playable the moment the upload call returns. If the assistant's output skips straight to uploading without creating the object first, or returns a playback URL immediately without a status check, that's a sign it filled a gap with a plausible guess instead of the documented sequence, worth catching before it ships.

Checking the output against the real docs

Three things are worth verifying specifically, not just reading the code and assuming it looks right: that the order of operations matches create-then-upload, that any status check polls rather than assumes readiness, and that the API key type used in any example matches what the task actually needs. None of this replaces testing the endpoint against the real API, it's a first pass to catch the kind of error that reads as plausible code but doesn't match how the platform actually behaves.

When the output gets it wrong

The fix is usually more specific than "try again." If the assistant skipped the create-then-upload sequence, point it back at the exact instruction rather than rephrasing the original ask: "media-video.md says a media object gets created first, then the file is uploaded separately, update the endpoint to do that." That's a more useful correction than restating the whole task, since it tells the assistant exactly which documented rule its first attempt didn't follow, instead of leaving it to guess what changed. Anthropic's own published guidance on working with Claude Code makes the same general point: specific, targeted correction against a concrete reference produces better follow-up output than a vague "that's not quite right" and another attempt at guessing. The same applies to the status-polling mistake: naming the specific method (getDetail) and the specific status value it should check for gets a corrected version faster than a vague "make sure it checks if the video is ready," which tends to produce a second guess rather than an actual fix.

What the wrong version actually looks like

Concretely, a first attempt that skipped the documented sequence often looks like this, uploading directly without creating the video object first:

app.post('/upload', async (req, res) => {
  const result = await client.uploadVideo(req.file.path)
  res.json({ url: result.playbackUrl })
})

That reads as reasonable code, it compiles, it has the right general shape, but it invents a single-step upload-with-immediate-URL flow that doesn't match how the documented API actually works: uploadVideo() takes a video ID that has to come from a prior create() call, and encoding isn't instant, so there's no playback URL available the moment the upload call returns. The corrected version follows the documented sequence directly:

app.post('/upload', async (req, res) => {
  const video = await client.video.create({ title: req.body.title })
  await client.uploadVideo(video.data.id, req.file.path)
  res.json({ videoId: video.data.id, status: 'processing' })
})

The difference isn't stylistic, the first version simply won't work against the real API, since it's calling a method with arguments that don't match what's documented. Catching that requires actually knowing what the reference file says, not just skimming the generated code for something that looks plausible, which is the real argument for reading the section file yourself at least once rather than treating it purely as something the assistant consumes on your behalf.

Frequently Asked Questions

Do I need to attach every llms.txt section file for this to work?
No. Attaching only the files relevant to the current task, media-video.md for an upload endpoint, keeps the assistant focused and avoids diluting context with unrelated resources.

Should I use a full-access API key for this kind of task?
No. An upload endpoint only needs an upload-only key; there's no reason to hand a coding assistant broader access than the task requires.

What's the most common mistake in AI-generated upload code for this API?
Skipping the initial video.create() call and uploading directly, or assuming a video is playable immediately after upload instead of polling for a "done" status.

Does this work the same way in ChatGPT or GitHub Copilot?
The same section files work in either; the mechanism differs (attaching the file in ChatGPT, referencing it with # in Copilot Chat), but the underlying content and what to check in the output is the same.

Do I still need to test the generated endpoint manually?
Yes. AIOZ Stream's own documentation says to verify generated code against live API behavior, and that applies here the same as anywhere else.

What's the most effective way to correct a wrong first attempt?
Point at the specific documented rule the output missed, rather than restating the original task. Naming the exact method or file section that contradicts what was generated gets a fixed version faster than a vague "that's not right, try again."

Related Reading

• What Is llms.txt?: what's actually inside the files this article puts to use
• AIOZ Stream API Keys: choosing the right key scope for a task like this
• Getting Started with the AIOZ Stream Node.js SDK: the exact create/upload/status methods a correct implementation should call

References

• AIOZ Stream AI documentation: the official source for the section files and setup instructions referenced above
• AIOZ Stream Media Video API documentation: the canonical reference to check generated code against