Video Generations

Async video generation via the marketplace. Submit a job, poll for status, retrieve results.

Submit Job

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "media.job",
  "kind": "video",
  "status": "queued",
  "created": 1713200000,
  "expires_at": 1713201800,
  "estimated_cost_usdc": "102000",
  "max_cost_usdc": "112200",
  "poll_url": "/v1/video/generations/550e8400-...",
  "cancel_url": "/v1/video/generations/550e8400-...",
  "job_token": "mjt_abc123..."
}

Image-to-Video

Pass a source image to animate a still (image-to-video), interpolate between two stills (transition), or condition on reference frames.

• Discovering models: image-to-video models carry an -image-to-video id suffix (e.g. seedance-2-0-image-to-video, wan-2-7-image-to-video, seedance-1-5-pro-image-to-video) and list image-to-video in their supported_parameters. Query /v1/models and /api/markets for the live set.
• Required input: an image-to-video-only model (no text-to-video) requires a source image; a request without one returns 400. Transition models require both a start and an end frame.
• Frames & roles: the simplest form is a single image_url (the start frame). For a transition, add end_image_url, or use input_images with explicit roles. Untagged input_images are positional — [start] or [start, end]; with three or more images, tag each with a role. Roles a model doesn't support are ignored — an extra frame won't fail the request.
• Source form: https:// URL or data: URI; bare base64 (without the data: prefix) and http:// URLs are rejected. URLs are passed to the provider as-is — the marketplace never fetches them.

{
  "model": "seedance-2-0-image-to-video",
  "prompt": "slow dolly-in as the waves roll",
  "image_url": "https://example.com/first-frame.png",
  "duration_seconds": 5
}

Poll Status

{
  "id": "550e8400-...",
  "object": "media.job",
  "kind": "video",
  "status": "succeeded",
  "created": 1713200000,
  "expires_at": 1713201800,
  "progress": 1.0,
  "results": [
    {
      "artifact_index": 0,
      "url": "https://api.surplusintelligence.ai/v1/media/artifacts/550e8400-.../0",
      "content_type": "video/mp4",
      "duration_seconds": 10,
      "width": 1920,
      "height": 1080,
      "bytes": 5000000
    }
  ],
  "usage": {
    "seller_cost_usdc": "80000",
    "buyer_cost_usdc": "96000",
    "settlement_status": "confirmed"
  }
}

{
  "id": "550e8400-...",
  "object": "media.job",
  "kind": "video",
  "status": "succeeded",
  "created": 1713200000,
  "expires_at": 1713201800,
  "progress": 1.0,
  "results": [
    {
      "artifact_index": 0,
      "url": "$SURPLUS_BASE_URL/media/artifacts/550e8400-.../0",
      "content_type": "video/mp4",
      "duration_seconds": 10,
      "width": 1920,
      "height": 1080,
      "bytes": 5000000
    }
  ],
  "usage": {
    "seller_cost_usdc": "80000",
    "buyer_cost_usdc": "96000",
    "settlement_status": "confirmed"
  }
}

Downloading the result

results[].url is an authenticated URL on this API, not a public link. Fetch it with the same Authorization: Bearer *** you submitted with, or with the job's job_token:

curl -L -H "X-Job-Token: $JOB_TOKEN" \
  https://api.surplusintelligence.ai/v1/media/artifacts/$JOB_ID/0 -o out.mp4

curl -L -H "X-Job-Token: $JOB_TOKEN" \
  $SURPLUS_BASE_URL/media/artifacts/$JOB_ID/0 -o out.mp4

Follow redirects (-L): SI-hosted artifacts answer with a 302 to short-lived storage. A few models return a provider-hosted URL instead, in which case url is that provider link and needs no header.

Artifacts do not live forever. The retention window runs from when the job reached a terminal state — 3 hours by default, and never longer than the provider keeps a relayed file — and stored artifacts are purged within a day regardless. Download promptly: past the window a fetch may still succeed for a short time, and then stops working. We are rolling out a clear 404 artifact_expired for that case; until then an expired fetch surfaces as a plain 404.

Cancel Job

Auth: API key OR X-Job-Token header.

Cancellation is best-effort. If the provider has already completed the job, it may transition to succeeded instead.

Errors

A 404 is a statement about supply and will not fix itself on retry; a 503 is transient.

Cost Model

• Costs are USDC microdollars (1 USD = 1,000,000 microdollars).
• Download artifacts are cached/proxied for buyer access. Default artifact retention is 3 hours (MEDIA_ARTIFACT_TTL_SECONDS can override it).
• Seller selection prices every candidate offer from the catalog at submit time; a cost-multiplier offer applies its multiplier to that price. The provider's own final price is reconciled at settlement.

• estimated_cost_usdc is the buyer estimate at submit time.
• max_cost_usdc is the reservation ceiling and the most you can be charged for the job — settlement is capped at it.
• It is not simply a percentage of estimated_cost_usdc, and it can be several times larger. We reserve enough to fail over to any seller in the candidate set without asking you again, so the ceiling is sized on the priciest candidate, not on the one we chose. A safety buffer is then applied on top: 10% for text-to-video and music, and 2× for image-input (image-to-video, transition, reference) jobs, whose final price is the provider's own and is only known when the render finishes. A job quoted at $0.08 against a set whose dearest member is 5× the cheapest therefore discloses a ceiling near $0.82. You are charged what the render actually costs, never the ceiling — the ceiling is only what we hold.
• Jobs expire after 30 minutes if not completed. Completed artifact download retention defaults to 3 hours.