> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neural4d.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本生成模型

> 通过文本提示词生成 3D 模型。支持控制模型数量、网格质量、目标面数以及是否仅生成网格。未传新参数时保持原有默认行为。

## 授权

<ParamField header="Authorization" type="string" required default={'Bearer ${YOUR_API_KEY}'}>
  使用 Neural4D 网站提供的 Bearer token。
</ParamField>

## 请求体 <span className="api-content-type">application/json</span>

<Tabs sync={false}>
  <Tab title="Option 1">
    <ParamField body="prompt" type="string" required>
      用于生成 3D 模型的文本提示词。

      示例：`"people"`。
    </ParamField>

    <ParamField body="mesh_quality" type="enum<string>" required>
      标准网格质量。

      可选值：`standard`。
    </ParamField>

    <ParamField body="modelCount" type="integer" default={4}>
      生成模型的数量。

      取值范围：`1 <= x <= 4`。
    </ParamField>

    <ParamField body="disablePbr" type="enum<integer>" default={0}>
      PBR 开关。使用 `0` 开启 PBR，使用 `1` 关闭 PBR。

      可选值：`0`、`1`。
    </ParamField>

    <ParamField body="onlyGenerateMesh" type="boolean" default={false}>
      是否仅生成网格，不生成纹理或 PBR 输出。
    </ParamField>

    <ParamField body="faceNum" type="integer">
      标准质量的目标面数。

      取值范围：`100000 <= x <= 500000`。

      默认值：`500000`。
    </ParamField>
  </Tab>

  <Tab title="Option 2">
    <ParamField body="prompt" type="string" required>
      用于生成 3D 模型的文本提示词。

      示例：`"people"`。
    </ParamField>

    <ParamField body="mesh_quality" type="enum<string>" default="high">
      高或超高网格质量。

      可选值：`high`、`extra_high`。

      省略此字段时也使用该分支。
    </ParamField>

    <ParamField body="modelCount" type="integer" default={4}>
      生成模型的数量。

      取值范围：`1 <= x <= 4`。
    </ParamField>

    <ParamField body="disablePbr" type="enum<integer>" default={0}>
      PBR 开关。使用 `0` 开启 PBR，使用 `1` 关闭 PBR。

      可选值：`0`、`1`。
    </ParamField>

    <ParamField body="onlyGenerateMesh" type="boolean" default={false}>
      是否仅生成网格，不生成纹理或 PBR 输出。
    </ParamField>

    <ParamField body="faceNum" type="integer">
      高或超高质量的目标面数。

      取值范围：`500000 <= x <= 1000000`。

      默认值：`1000000`。
    </ParamField>
  </Tab>
</Tabs>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://alb.neural4d.com:3000/api/generateModelWithText \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '
  {
    "prompt": "people",
    "modelCount": 1,
    "disablePbr": 0,
    "onlyGenerateMesh": false,
    "mesh_quality": "high",
    "faceNum": 1000000
  }
  '
  ```

  ```python Python theme={null}
  import requests

  response = requests.request(
      "POST",
      "https://alb.neural4d.com:3000/api/generateModelWithText",
      headers={
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
      },
      json={
        "prompt": "people",
        "modelCount": 1,
        "disablePbr": 0,
        "onlyGenerateMesh": false,
        "mesh_quality": "high",
        "faceNum": 1000000
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://alb.neural4d.com:3000/api/generateModelWithText", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "prompt": "people",
      "modelCount": 1,
      "disablePbr": 0,
      "onlyGenerateMesh": false,
      "mesh_quality": "high",
      "faceNum": 1000000
    }),
  });
  const data = await response.json();
  console.log(data);
  ```

  ```typescript TypeScript theme={null}
  const response: Response = await fetch("https://alb.neural4d.com:3000/api/generateModelWithText", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "prompt": "people",
      "modelCount": 1,
      "disablePbr": 0,
      "onlyGenerateMesh": false,
      "mesh_quality": "high",
      "faceNum": 1000000
    }),
  });
  const data = await response.json();
  console.log(data);
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.*;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://alb.neural4d.com:3000/api/generateModelWithText"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("{\n      \"prompt\": \"people\",\n      \"modelCount\": 1,\n      \"disablePbr\": 0,\n      \"onlyGenerateMesh\": false,\n      \"mesh_quality\": \"high\",\n      \"faceNum\": 1000000\n    }"))
      .build();
  HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
    "strings"
  )

  payload := strings.NewReader("{\n  \"prompt\": \"people\",\n  \"modelCount\": 1,\n  \"disablePbr\": 0,\n  \"onlyGenerateMesh\": false,\n  \"mesh_quality\": \"high\",\n  \"faceNum\": 1000000\n}")
  req, _ := http.NewRequest("POST", "https://alb.neural4d.com:3000/api/generateModelWithText", payload)
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  bodyBytes, _ := io.ReadAll(resp.Body)
  fmt.Println(string(bodyBytes))
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "json"

  uri = URI("https://alb.neural4d.com:3000/api/generateModelWithText")
  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = {
    "prompt": "people",
    "modelCount": 1,
    "disablePbr": 0,
    "onlyGenerateMesh": false,
    "mesh_quality": "high",
    "faceNum": 1000000
  }.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
  puts response.body
  ```

  ```php PHP theme={null}
  <?php

  $ch = curl_init("https://alb.neural4d.com:3000/api/generateModelWithText");
  curl_setopt_array($ch, [
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ["Authorization: Bearer <token>", "Content-Type: application/json"],
      CURLOPT_POSTFIELDS => "{\n  \"prompt\": \"people\",\n  \"modelCount\": 1,\n  \"disablePbr\": 0,\n  \"onlyGenerateMesh\": false,\n  \"mesh_quality\": \"high\",\n  \"faceNum\": 1000000\n}",
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```csharp C# theme={null}
  using System.Net.Http;
  using System.Text;

  using var client = new HttpClient();
  using var request = new HttpRequestMessage(HttpMethod.Post, "https://alb.neural4d.com:3000/api/generateModelWithText");
  request.Headers.TryAddWithoutValidation("Authorization", "Bearer <token>");
  request.Headers.TryAddWithoutValidation("Content-Type", "application/json");
  request.Content = new StringContent("{\n  \"prompt\": \"people\",\n  \"modelCount\": 1,\n  \"disablePbr\": 0,\n  \"onlyGenerateMesh\": false,\n  \"mesh_quality\": \"high\",\n  \"faceNum\": 1000000\n}", Encoding.UTF8, "application/json");
  using var response = await client.SendAsync(request);
  Console.WriteLine(await response.Content.ReadAsStringAsync());
  ```
</RequestExample>

## 响应

<Tabs sync={false}>
  <Tab title="200">
    生成任务已接受，或请求未通过内容审核。

    <Tabs sync={false}>
      <Tab title="Option 1">
        <ResponseField name="type" type="enum<string>" required>
          响应来源或类型标记。

          可选值：`sys`。

          示例：`"sys"`。
        </ResponseField>

        <ResponseField name="message" type="string" required>
          生成状态消息。

          可选值：`Generating`。

          示例：`"Generating"`。
        </ResponseField>

        <ResponseField name="uuids" type="string<uuid>[]" required>
          可在后续查询模型时使用的 UUID 列表。

          数组长度：`1 - 4` 个元素。
        </ResponseField>

        <ResponseField name="uploadedImageUrl" type="string<uri> | null" required>
          纯文本生成时始终为 null。
        </ResponseField>

        <ResponseField name="pointsDeducted" type="integer | null">
          可用时返回本次请求扣除的点数。
        </ResponseField>

        <ResponseField name="generationConfig" type="object">
          本次生成请求实际采用的标准化面数配置。

          <Expandable title="child attributes">
            <ResponseField name="faceNum" pre={["generationConfig."]} type="object" required>
              生成任务的面数限制及实际采用的标准化值。

              <Expandable title="child attributes">
                <ResponseField name="default" pre={["generationConfig.faceNum."]} type="integer" required>
                  所选网格质量对应的默认面数。
                </ResponseField>

                <ResponseField name="min" pre={["generationConfig.faceNum."]} type="integer" required>
                  所选网格质量允许的最小面数。
                </ResponseField>

                <ResponseField name="max" pre={["generationConfig.faceNum."]} type="integer" required>
                  所选网格质量允许的最大面数。
                </ResponseField>

                <ResponseField name="value" pre={["generationConfig.faceNum."]} type="integer" required>
                  生成任务实际采用的标准化面数。
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Tab>

      <Tab title="Option 2">
        <ResponseField name="limitType" type="enum<integer>" required>
          内容审核结果代码。

          可选值：`3`、`4`。
        </ResponseField>

        <ResponseField name="message" type="string" required>
          内容审核提示信息。
        </ResponseField>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="400">
    请求参数无效。

    <ResponseField name="errors" type="object[]" required>
      请求参数校验错误列表。

      <Expandable title="child attributes">
        <ResponseField name="msg" pre={["errors[]."]} type="string" required>
          可读的参数校验错误信息。
        </ResponseField>

        <ResponseField name="path" pre={["errors[]."]} type="string" required>
          未通过校验的请求字段。
        </ResponseField>

        <ResponseField name="location" pre={["errors[]."]} type="string" required>
          无效字段所在的请求位置。
        </ResponseField>

        <ResponseField name="type" pre={["errors[]."]} type="string">
          校验错误类别。
        </ResponseField>

        <ResponseField name="value" pre={["errors[]."]} type="object | null">
          可用时返回被拒绝的请求值。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="401">
    身份认证失败。
  </Tab>

  <Tab title="402">
    账户、IP 或点数限制阻止了本次请求。

    <ResponseField name="message" type="string">
      可读的 API 错误信息。
    </ResponseField>

    <ResponseField name="error" type="string">
      可用时返回内部或下游错误说明。
    </ResponseField>
  </Tab>

  <Tab title="403">
    当前账户无权执行本次生成。

    <ResponseField name="message" type="string">
      可读的 API 错误信息。
    </ResponseField>

    <ResponseField name="error" type="string">
      可用时返回内部或下游错误说明。
    </ResponseField>
  </Tab>

  <Tab title="429">
    请求频率超过限制。

    <ResponseField name="message" type="string">
      可读的 API 错误信息。
    </ResponseField>

    <ResponseField name="error" type="string">
      可用时返回内部或下游错误说明。
    </ResponseField>
  </Tab>

  <Tab title="500">
    生成服务或内部服务不可用。

    <ResponseField name="message" type="string">
      可读的 API 错误信息。
    </ResponseField>

    <ResponseField name="error" type="string">
      可用时返回内部或下游错误说明。
    </ResponseField>
  </Tab>
</Tabs>

<ResponseExample>
  ```json 200 generating theme={null}
  {
    "type": "sys",
    "message": "Generating",
    "uuids": [
      "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    ],
    "generationConfig": {
      "faceNum": {
        "default": 1000000,
        "min": 500000,
        "max": 1000000,
        "value": 1000000
      }
    },
    "uploadedImageUrl": null
  }
  ```

  ```json 200 moderated theme={null}
  {
    "limitType": 3,
    "message": "Please check the prompt."
  }
  ```

  ```json 400 Example theme={null}
  {
    "errors": [
      {
        "type": "field",
        "value": 5,
        "msg": "modelCount must be an integer between 1 and 4 (inclusive)",
        "path": "modelCount",
        "location": "body"
      }
    ]
  }
  ```

  ```json 401 Example theme={null}
  "Unauthorized"
  ```

  ```json 402 Example theme={null}
  {
    "message": "Insufficient points or account restricted"
  }
  ```

  ```json 403 Example theme={null}
  {
    "message": "Generation is not available for the current account"
  }
  ```

  ```json 429 Example theme={null}
  {
    "message": "Too many requests from this user, please try again after a minute."
  }
  ```

  ```json 500 Example theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>