Skip to content

feat(media): Hyper3D Rodin provider (text-to-3D, image-to-3D) - #45

Open
duanbing wants to merge 1 commit into
mainfrom
feat/hyper3d-rodin
Open

duanbing wants to merge 1 commit into
mainfrom
feat/hyper3d-rodin

Conversation

@duanbing

Copy link
Copy Markdown

Adds a hyper3d media proxy provider for Hyper3D's Rodin 3D generation API, so every Rodin tier can be served as text-to-3D and image-to-3D: Gen-2.5 (Extreme-Low to Extreme-High), Gen-2, and Gen-1/1.5 (Sketch, Regular, Detail, Smooth).

  • Submit: POST /api/v2/rodin as multipart. The tier comes from proxy.path. Image tasks upload one to five image_urls as images file parts. The images are fetched through public_url::client(), so internal addresses are refused.
  • Hyper3D can reject with HTTP 201 and a body-level error, so the provider checks both the status and the body.
  • Poll: POST /status with jobs.subscription_key. Every job must be Done, and any Failed job fails the task. Transient poll errors are retried up to 6 times in a row. Submits are never retried.
  • Results: POST /download with the task uuid. The callback lists the model file first and a preview image second, and carries the submit's consumed as usage.credits for credit billing.
  • Only documented form fields are forwarded, and arrays become repeated fields.
  • Config: host from HYPER3D_API_BASE (default https://api.hyper3d.com/api/v2), key from HYPER3D_API_KEY.

Tests: 9 unit tests cover the form fields, prompt and image rules, rejections inside a 201 body, ids and credits, job status, result file selection, image type detection and the callback body. Clippy with --all-targets reports nothing for the new code. The only clippy error is the minimax.rs one fixed in #44.

Not yet checked against a live task: the exact /download file names. Result selection goes by file extension, so it doesn't depend on them.

A `proxy.provider = "hyper3d"` media variant submits to Hyper3D's Rodin API
(`POST /api/v2/rodin`, multipart, the Rodin `tier` from `proxy.path`), polls
`POST /status` with `jobs.subscription_key`, and lists results with
`POST /download` using the task `uuid`.

- Image tasks upload one to five `image_urls` as `images` file parts. The
  images are fetched through `public_url::client()`, so internal addresses
  are refused like any other caller-supplied file URL.
- A rejection can arrive as HTTP 201 with a non-empty `error`; both the
  status and the body are checked.
- Every job must be `Done`; any `Failed` job fails the task. 429 / 5xx /
  network errors on a status poll are retried up to 6 times in a row.
  Submits are never retried.
- The callback lists the model file first (the requested
  `geometry_file_format`, else the first 3D file) and a preview image
  second, and carries the submit's `consumed` as `usage.credits`.
- Only documented Rodin form fields are forwarded; arrays become repeated
  fields. Host from `HYPER3D_API_BASE` (default
  https://api.hyper3d.com/api/v2), key from `HYPER3D_API_KEY`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant