Agent API

Send reference material and instructions; the video agent decides everything (story, shots, prompt, canvas), renders, optionally reviews the result against your instructions and tries again, and hands back one or more videos. No questions are asked back and nothing needs confirming.

Every call is authenticated with an API key. Create one at www.happypony.io → API Keys; the full key is shown once, so store it somewhere safe. Revoke a leaked key there and create a new one.

Authorization: Bearer hp_…

Session cookies are not accepted on these endpoints. Runs belong to the key's user: another user's run id answers 404.

Base URL below: https://api.happypony.io.

Upload a file

POST /api/v1/agent/runs/uploads (multipart/form-data)

For media that isn't at a public URL: upload it first, then pass the returned url in any *_url field of Start a run — reference_image_urls, reference_video_urls, reference_audio_urls, first_frame_url or last_frame_url. Upload one file per request.

curl -X POST https://api.happypony.io/api/v1/agent/runs/uploads \
  -H "Authorization: Bearer $HP_KEY" \
  -F file=@selfie.png

{ "url": "https://…signed…", "kind": "image", "expires_in": 7200 }

The response is 201.

• url is a presigned link to your private copy, valid for expires_in seconds (2 hours). Start the run before it expires; once the run is created the file is attached to it and the link no longer matters.
• Accepted types: images jpg/png/webp, video mp4/mov/webm/mkv, audio wav/mp3/m4a/aac/ogg/flac.
• Size caps: image 20 MB, audio 30 MB, video 200 MB.
• Uploading is free; credits are only spent on renders.

Two local images into one run:

up() { curl -s -X POST https://api.happypony.io/api/v1/agent/runs/uploads \
         -H "Authorization: Bearer $HP_KEY" -F "file=@$1" | jq -r .url; }
A=$(up selfie3.png); B=$(up selfie4.png)
curl -X POST https://api.happypony.io/api/v1/agent/runs \
  -H "Authorization: Bearer $HP_KEY" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"The two girls have a bar fight\", \"reference_image_urls\": [\"$A\", \"$B\"], \"variants\": 2, \"feedback_loops\": 1}"

Start a run

POST /api/v1/agent/runs

curl -X POST https://api.happypony.io/api/v1/agent/runs \
  -H "Authorization: Bearer $HP_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 15 second ad for this trail shoe: a runner at dawn, energetic, ends on the logo.",
    "reference_image_urls": ["https://cdn.example.com/shoe-front.png", "https://cdn.example.com/shoe-side.png"],
    "reference_audio_urls": ["https://cdn.example.com/voice.mp3"],
    "hints": { "duration": 15, "aspect_ratio": "9:16", "short_edge": 768, "tier": "quality", "language": "en" },
    "variants": 2,
    "feedback_loops": 1
  }'

{
  "request_id": "6f1c…",
  "status": "IN_QUEUE",
  "status_url": "https://api.happypony.io/api/v1/agent/runs/6f1c…/status",
  "response_url": "https://api.happypony.io/api/v1/agent/runs/6f1c…",
  "cancel_url": "https://api.happypony.io/api/v1/agent/runs/6f1c…/cancel"
}

The response is 202. Unknown fields are rejected (400), so a typo never silently changes what is rendered.

A hint you give is binding: the agent cannot override it. Anything you leave out, the agent chooses.

Media URLs

Files you uploaded are passed the same way, by their URL. Each URL is downloaded when the run is created and stored as a private attachment, so a bad URL fails the request (400 invalid_media, naming the field) instead of a run later. The rules:

• https:// only, default port, no credentials in the URL.
• The host must resolve to public addresses only (loopback, private, link-local, carrier-NAT and multicast ranges are refused, including after redirects). Up to 3 redirects, each re-checked.
• Content type must match the field: images jpg/png/webp, video mp4/mov/webm/mkv, audio wav/mp3/m4a/aac/ogg/flac. application/octet-stream is accepted when the file extension says so.
• Size caps: image 20 MB, audio 30 MB, video 200 MB. Timeouts: 30 s / 45 s / 120 s.

Credits and limits

• Quote and pre-check. The run's worst case is variants × (1 + feedback_loops) × the price of one video, where one video is priced from your hints; without hints, at quality, 768 short edge and 15 s. If your balance is below it, the request is 402: {"error":"insufficient_credits","required":600,"available":420}. The agent is held to that per-video price: it will not propose a dearer video. Give hints.duration / short_edge if you want longer or larger videos budgeted for.
• What is actually charged is only the renders that were submitted, at the moment each is submitted. A render that fails is refunded automatically. A run that stops early (satisfied review, cancellation, failure) costs less than the quote. credits_used / total_credits report the actual amount.
• Concurrency. At most 3 active (IN_QUEUE / IN_PROGRESS) runs per user; the fourth is 429 too_many_runs.

Poll for status

GET /api/v1/agent/runs/:id/status

{
  "request_id": "6f1c…",
  "status": "IN_PROGRESS",
  "phase": "rendering",
  "created_at": "2026-09-28T10:00:00.000Z",
  "started_at": "2026-09-28T10:00:03.000Z",
  "completed_at": null,
  "variants": [
    { "variant": 1, "state": "running", "phase": "rendering", "iteration": 1, "max_iterations": 2,
      "renders_finished": 0, "render_status": "pending", "queue_position": 3, "eta_seconds": 240 },
    { "variant": 2, "state": "running", "phase": "analysing", "iteration": 0, "max_iterations": 2, "renders_finished": 0 }
  ],
  "credits_used": 60,
  "quoted_credits": 240,
  "queue_position": 3,
  "eta_seconds": 240,
  "status_url": "…", "response_url": "…", "cancel_url": "…"
}

status uses the batch queue's names:

phase (run level: the most advanced running variant; null once finished):

Per variant, iteration counts renders started and max_iterations is feedback_loops + 1. state is running, done or failed. Polling every 10–30 s is plenty; there are no webhooks.

Get the result

GET /api/v1/agent/runs/:id

{
  "request_id": "6f1c…",
  "status": "COMPLETED",
  "videos": [
    { "variant": 1, "iteration": 1, "final": false, "url": "https://…signed…", "activity_id": 812,
      "credits": 120,
      "parameters": { "title": "Trail shoe dawn run", "mode": "from references", "tier": "quality", "duration": 15,
                      "short_edge": 768, "aspect_ratio": "9:16", "inputs": "reference images img1, img2", "seed": 1804289383,
                      "brief": "A runner laces the shoe at dawn, then…" },
      "prompt_used": "…",
      "review": { "satisfied": false, "summary": "The shoe is not visible in the last shot.", "issues": ["logo missing"], "revision": "end on a close-up of the logo" } },
    { "variant": 1, "iteration": 2, "final": true, "url": "https://…signed…", "activity_id": 815,
      "credits": 120, "parameters": { "…": "…" }, "prompt_used": "…" }
  ],
  "total_credits": 240,
  "variant_errors": [{ "variant": 2, "error": "the content check refused every plan (minor): …" }],
  "log": [
    { "at": "2026-09-28T10:00:03.100Z", "kind": "run", "message": "Run started", "data": { "variants": 2, "feedback_loops": 1 } },
    { "at": "2026-09-28T10:00:20.400Z", "variant": 1, "kind": "plan", "message": "Proposed \"Trail shoe dawn run\" (120 credits)", "data": { "credits": 120, "settings": { }, "prompt": "…" } }
  ]
}

• videos has one entry per finished render. final: true marks the render the run delivers for that variant: the one that satisfied the review, or the last one when the loops ran out (or when a later render failed). Use final, not the order.
• url is a presigned download link, valid for 2 hours. Fetch the run again for a fresh one.
• credits is what that render cost; total_credits is the run's total after refunds.
• parameters are the settings the render was submitted with, as the agent chose them (within your hints): mode (text to video, from frames or from references), tier, duration (seconds), short_edge (pixels), aspect_ratio, inputs (which of your files it used, by label: img1 is your first image), seed, and brief, the agent's plan in plain words. prompt_used is the full prompt the renderer received.
• review is present when that render was reviewed. The review sees sampled frames, not the audio.
• log is every step in order, each {at, variant?, iteration?, kind, message, data?}. Kinds: run, phase, input, agent, plan, job, review, variant, cancel, error. It never contains signed URLs, the agent's system prompt or its private reasoning.

While a run is in progress the same endpoint returns the videos finished so far.

Runs also appear in the video agent's chat history on happypony.io, marked API: one read-only chat per run, with your instructions and each video's plan, render and review in order.

Cancel

PUT /api/v1/agent/runs/:id/cancel

{ "request_id": "6f1c…", "status": "CANCELLED", "renders_cancelled": 1, "renders_still_running": 0 }

The run stops within seconds. Renders still waiting in the render queue are cancelled there and refunded. A render a worker has already started cannot be stopped: it finishes, its credits stay spent, and it does not appear in the run's videos. Cancelling a run that already finished is 409 not_cancellable.

Errors

How a run works

1. The request is validated, quoted and its media stored. Each variant gets its own private agent conversation (never shown in the chat history) starting from your instructions.
2. A runner process claims the run (with a lease it keeps renewing, so a restart or another replica picks it up where it stopped, without submitting a render twice), and drives every variant in parallel: the agent analyses the material and proposes a video; the proposal is confirmed automatically at the quoted price and submitted to the render queue.
3. When a render finishes and loops remain, sampled frames plus your instructions and the prompt go to the vision model for a structured critique. If it is satisfied the variant is done; otherwise the agent revises and proposes again.
4. A content-check refusal is fed back to the agent, which revises the plan (up to 3 times per variant). Any other hard failure ends that variant only.