如何使用 ModelFold Studio 從單一可編輯範本渲染個人化圖片

If the layout is already approved and only the speaker name or session title changes, you can fill a template instead of asking an image model to recreate the design for every record.

ModelFold Studio exposes a rendering endpoint for that workflow: one editable document, an array of variable values, and one output image per row.

Disclosure: this is a ModelFold team tutorial. Requests below are illustrative and have not been submitted as paid renders for this article. Sample names and sessions are fictional input data, not customer examples.

Prepare the template first

Open Studio and prepare your own template with text placeholders such as {{name}} and {{session}}. Save it as a template in your account. The API lists your templates and their detected variables:

# Assumes MODELFOLD_API_KEY is set privately in your shell.
curl -sS 'https://modelfold.ai/v1/studio/templates' \
  -H "Authorization: Bearer $MODELFOLD_API_KEY"

Use an ID returned for your own account, not a public gallery slug or the example number from another guide. Inspect its variables, width, and height before building a batch.

Text placeholders are replaced by matching row values. A missing value becomes an empty string, so validate your data before rendering. A long session title may need a different layout: substitution is not a guarantee that arbitrary text fits.

Submit a small batch

Create render-request.json, replacing YOUR_TEMPLATE_ID with your own returned ID:

{
  "template_id": "YOUR_TEMPLATE_ID",
  "rows": [
    {"name": "Alex", "session": "Shipping a Small API"},
    {"name": "Sam", "session": "Designing Useful Defaults"}
  ],
  "page": 0,
  "format": "png",
  "scale": 1
}

Then submit it when you are ready to spend render credits:

curl -sS 'https://modelfold.ai/v1/studio/render' \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @render-request.json > render-response.json

This endpoint is synchronous. It is different from the async task API used for generating complete PPT decks. A render request accepts up to 100 rows and selects one zero-based page. It supports PNG or JPG and a scale from 0.25 to 2. For a single output, use variables instead of a batch of rows.

Inspect every row result

A successful HTTP response does not mean every image rendered. The response's results array contains per-row success flags and either a URL or an error. With jq installed:

# Print successful image URLs.
jq -r '.results[] | select(.ok == true) | .url' render-response.json

# Inspect failures before deciding what to retry.
jq '.results[] | select(.ok != true)' render-response.json

# Read the final charge reported for the batch.
jq '.credits' render-response.json

Preserve the input row order alongside the result array so you can identify failed records. The documented default is one credit per successful image; pricing is configurable. The implementation reserves for the requested batch, then settles against successful renders. Failed images are not charged.

Do not apply the deck-creation API's idempotency promise to /v1/studio/render: this render endpoint does not document an Idempotency-Key guarantee. If a client times out after submission, check account usage before blindly resending the batch.

Where AI and PPT fit

This API renders an existing Studio document. There is currently no public endpoint for generating a single design from a text prompt. You can start a design in the Studio interface and reuse its layout with data.

For a complete presentation, ModelFold PPT 1.1 uses the async jobs API and can return a deck for further editing in Studio. PPTX exports aim to preserve editable text and supported shapes; some other elements are rasterized. That is a separate workflow from rendering one selected page per data row.

See the Studio API reference for rendering and the PPT model reference for deck generation. Test one representative row, then a long-text row, before scaling up.