端点

修改应用

像编辑器那样，根据一条指令修改应用。

POSThttps://www.setherion.com/api/v1/projects/{id}/edit

套餐：所有套餐

执行的修改与在 Setherion 编辑器里写下一条指令完全相同。它和编辑器输入框背后是同一条路径，所以积分、套餐规则和安全检查都一样，结果会被保存，并像其他修改一样记入应用的历史记录。

你需要有修改这个应用的权限：应用是你的，或者你是它所在工作区的编辑者或管理员，或者它以编辑者身份共享给了你。

积分从为这个应用付费的账户中扣除，也就是它的创建者，不一定是你。如果应用所在的工作区限制了你可以花费的额度，这个限制同样适用。

修改已经保存，但在应用发布之前不会上线。准备好之后，请调用发布应用。

请求

bash

curl -X POST https://www.setherion.com/api/v1/projects/7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14/edit \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Make the buttons green and add an opening hours section" }'

字段	类型	含义
`prompt`	string，必填	要修改的内容，可以用任何语言。前后的空格会被忽略。最多 4,000 个字符。
`model`	string，可选	不填时为 `auto`：Setherion 在你的套餐范围内选择，和编辑器里一样。如果你的套餐不包含所指定的模型，会换成套餐内最好的模型，而不是拒绝请求。

应用必须已经有代码。从未构建过的应用会返回 409。

修改完成后才返回

一次修改需要一到几分钟，请求在修改完成之前一直保持打开。运行超过大约 13 分钟的修改会被服务器中断。

在处理期间，Setherion 每 10 秒发送一个空格，这样你和我们之间的任何环节都不会关闭一条安静的连接。JSON 之前的空格仍然是有效的 JSON：请读取完整的响应体，再解析。

修改一旦开始，无论发生什么，状态码都是 200，由 ok 说明结果如何。响应的 X-Setherion-Run 头从一开始就带有这次修改的 runId，早于响应体。

关闭连接不会停止修改

如果你的客户端放弃等待或者连接断开，修改仍会继续，并且像你一直在等一样落到应用里，积分也会被花掉。请保留 X-Setherion-Run 头，并通过跟踪修改询问修改进行到哪里了。要中途停止修改，请在 Setherion 编辑器里，点击显示它正在运行的那张卡片上的 Stop。

响应

一次完成的修改：

json

{
  "ok": true,
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "changed": {
    "added": ["src/components/OpeningHours.tsx"],
    "modified": ["src/App.tsx", "src/index.css"],
    "removed": []
  }
}

字段	类型	含义
`ok`	boolean	修改完成并已保存时为 `true`。
`runId`	string	这次修改的 id。Setherion 无法确定时会省略。
`projectId`	string	被修改的应用。Setherion 无法确定时会省略。
`changed`	object	这次修改新增、更改和删除的文件，每一项都是排好序的路径列表。Setherion 无法确定时会省略，这和什么都没有改变不是一回事。
`builds`	`false`	仅在被修改的应用不再能构建时出现。修改已经写入，它的积分会退回。没有这个字段，并不保证应用能够构建。
`refundedCredits`	number	有积分退回时，退回了多少积分。

一次让应用构建失败的修改：

json

{
  "ok": true,
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "changed": { "added": [], "modified": ["src/App.tsx"], "removed": [] },
  "builds": false,
  "refundedCredits": 10
}

一次没有发生的修改：

json

{ "ok": false, "error": "This edit costs 10 credits and you have 3.", "outOfCredits": true }

只有当为这次修改付费的账户没有积分了，才会出现 outOfCredits，并且为 true。其他所有拒绝都是 ok: false，加上一个 error，没有别的内容。

修改为什么会返回 ok: false

这些都以状态码 200 返回，因为修改已经开始。

This edit costs 10 credits and you have 3.，并带有 outOfCredits: true。这个数字是该次修改的价格和你的余额。对于别人的应用，这句话是 This app's owner has no credits left this month, so this edit cannot run.，并且绝不会说出对方的余额。
You have used 40 of the 100 credits a month this workspace allows you on its owner's plan. Ask an admin to raise it.，并带有 outOfCredits: true，这是工作区所有者限制了你的花费额度时的情况。
You're working faster than our safety limit allows (120 an hour). You can carry on in about 12 minutes. 修改和构建的速度限制为每个账户每小时 120 次。
The edit stopped before it finished. Nothing was charged for it. 这次运行在完成之前就结束了。
The edit could not start. 或 The edit failed: ...，这是我们这边出了问题。请再试一次。

跟踪修改

GEThttps://www.setherion.com/api/v1/projects/{id}/edit?run={runId}

套餐：所有套餐

用来查看一次修改进行到哪里了，适合停止等待或者从未等待的客户端。免费，大约每分钟查询一次是安全的。

bash

curl "https://www.setherion.com/api/v1/projects/7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14/edit?run=b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61" \
  -H "Authorization: Bearer $SETHERION_API_KEY"

json

{
  "ok": true,
  "status": "done",
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "startedAt": "2026-10-16T15:13:02.118Z"
}

`status`	`ok`	含义
`running`	`true`	仍在处理。一分钟左右后再问一次。
`done`	`true`	已完成，并保存到应用里。准备好后再发布它。如果带有 `cutShort: true`，说明代码一写完就保存了，没有做收尾处理。
`stopped`	`false`	在完成之前被停止。应用里没有任何改动。
`failed`	`false`	失败。应用里没有任何改动。
`stalled`	`false`	已经好几分钟没有进展，很可能已经停了。请在 Setherion 里打开这个应用，看看它进行到哪里。

结果为 false 的情况也会带有一句 error，这次修改可以重新发送。这个响应不会列出更改过的文件：只有修改本身的响应才会列出。

状态码	`error`
`400`	`Say which edit, in "run": the runId its POST answered.`
`404`	`No such app on this account.` 或 `No such edit on this app.`

修改开始之前的错误

状态码	何时出现
`400`	`prompt` 缺失、为空，或超过 4,000 个字符。
`401`	密钥缺失、错误或已被撤销。
`404`	没有这个应用，或者你的密钥无权修改它。这包括你只能查看的应用。
`409`	应用还没有代码。请先在 Setherion 里构建它。

确切的错误信息

状态码	`error`
`400`	`Say what to change, in "prompt".`
`400`	`Keep "prompt" under 4,000 characters.`
`404`	`No such app on this account.`
`409`	`This app has no code yet. Build it in Setherion first, then edit it here.`

这个页面对你有帮助吗？

列出你的应用

发布应用

加入社区

提问、交流想法，看看别人在构建什么。