Skip to content

Clarify Seedance real-person profile ID lifecycle #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
think-back wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clarify Seedance real-person profile ID lifecycle #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 27 additions & 6 deletions guides/seedance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,9 +358,13 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons `
```
</CodeGroup>

The response includes a profile `id`, a `status`, and a one-time `verification_url`. Send `verification_url` to the real person and ask them to open it themselves. Do not publish this link.
The response includes a profile `id`, a `status`, and a one-time `verification_url`. The `id` is the stable Flatkey profile ID, such as `rph_...`. Save it immediately and reuse it for status checks, new verification sessions, and every asset that belongs to this person. Create one profile for each logical person.

If the link expires or the person needs another link, create a new verification session:
Flatkey binds the upstream real-person asset group after verification and manages that group internally. You do not need to create, store, or send the upstream group ID. If your application already has its own CRM or person ID, store a mapping from that ID to the returned Flatkey `rph_...` ID. This API does not require an `external_person_id` field.

Send `verification_url` to the real person and ask them to open it themselves. Do not publish this link.

If the link expires or the person needs another link, create a new verification session under the same profile ID. Do not create another profile for the same person:

<CodeGroup>
```bash Bash
Expand Down Expand Up @@ -392,7 +396,24 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef `

Wait until the profile status is `active` before creating assets. If it is `pending_verification` or `verifying`, wait and poll again. If it is `failed` or `expired`, create a new verification session.

#### 3. Create a real-person asset from a public URL
#### 3. Recover or manage multiple profiles

Keep the returned `rph_...` ID in your own user record. If you need to recover profiles or manage many people, list them with cursor pagination:

<CodeGroup>
```bash Bash
curl -sS "https://router.flatkey.ai/v1/real-persons?limit=20" \
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
```
```powershell Windows PowerShell
curl.exe -sS "https://router.flatkey.ai/v1/real-persons?limit=20" `
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
```
</CodeGroup>

Use each returned profile's `id` for later requests. If the response contains a non-empty `next_after`, request the next page with `?limit=20&after=NEXT_AFTER`. Listing profiles is a recovery and administration path; storing the `rph_...` ID when you create the profile is the primary lookup path.

#### 4. Create a real-person asset from a public URL

<CodeGroup>
```bash Bash
Expand All @@ -419,9 +440,9 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/asse
```
</CodeGroup>

#### 4. Upload a local file
#### 5. Upload a local file

Local upload uses `multipart/form-data` and is available only for real-person assets. Use one `file` field and let curl set the multipart boundary.
Local upload uses `multipart/form-data` and is available only for real-person assets. It also requires upload storage on the account or channel that serves the profile. Use one `file` field and let curl set the multipart boundary. If local upload returns `asset_channel_unavailable`, host the file at a public HTTPS URL and use the URL flow in the previous step.

<CodeGroup>
```bash Bash
Expand All @@ -444,7 +465,7 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/asse

The create response includes an asset ID or `asset_uri`, for example `asset://ast_1234567890abcdef1234567890abcdef`.

#### 5. Poll readiness and call Seedance
#### 6. Poll readiness and call Seedance

Real-person asset responses do not include `available_models`. List the assets under the profile until the asset `status` is `Active`:

Expand Down
33 changes: 27 additions & 6 deletions zh/guides/seedance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,9 +349,13 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons `
```
</CodeGroup>

响应会包含真人档案 `id`、`status` 和一次性的 `verification_url`。把 `verification_url` 交给本人，让本人打开并完成认证。不要公开这个链接。
响应会包含真人档案 `id`、`status` 和一次性的 `verification_url`。这个 `id` 是稳定的 Flatkey 真人档案 ID，例如 `rph_...`。拿到后立即保存，并在查询状态、重新创建认证会话和管理这个人的全部素材时复用。同一个自然人只创建一个真人档案。

如果链接过期，或本人需要新的链接，创建一个新的认证会话：
认证完成后，Flatkey 会在内部绑定并管理上游真人素材组。你的客户端不需要创建、保存或传递上游 GroupId。如果你的业务已经有 CRM 用户 ID 或人员 ID，请在自己的系统里保存“业务人员 ID → Flatkey `rph_...`”映射。这个接口不要求传 `external_person_id` 字段。

把 `verification_url` 交给本人，让本人打开并完成认证。不要公开这个链接。

如果链接过期，或本人需要新的链接，请在同一个真人档案 ID 下创建新的认证会话。不要为同一个人再建一个真人档案：

<CodeGroup>
```bash Bash
Expand Down Expand Up @@ -383,7 +387,24 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef `

等档案状态变成 `active` 后再创建素材。如果还是 `pending_verification` 或 `verifying`，稍后继续查。如果是 `failed` 或 `expired`，重新创建认证会话。

#### 3. 用公网 URL 创建真人素材
#### 3. 找回或管理多个真人档案

请把返回的 `rph_...` ID 保存到你自己的用户记录中。如果需要找回档案，或同一个客户需要管理多个真人，可以用游标分页列出真人档案：

<CodeGroup>
```bash Bash
curl -sS "https://router.flatkey.ai/v1/real-persons?limit=20" \
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
```
```powershell Windows PowerShell
curl.exe -sS "https://router.flatkey.ai/v1/real-persons?limit=20" `
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
```
</CodeGroup>

后续请求都使用列表中每个档案返回的 `id`。如果响应里的 `next_after` 非空，用 `?limit=20&after=NEXT_AFTER` 获取下一页。列表接口用于找回和管理；正常流程仍应在创建档案时立即保存 `rph_...` ID。

#### 4. 用公网 URL 创建真人素材

<CodeGroup>
```bash Bash
Expand All @@ -410,9 +431,9 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/asse
```
</CodeGroup>

#### 4. 上传本地文件
#### 5. 上传本地文件

本地上传使用 `multipart/form-data`，只用于真人素材。使用一个 `file` 字段，并让 curl 自动设置 multipart boundary。
本地上传使用 `multipart/form-data`，只用于真人素材，并且依赖承载该档案的账号或渠道已经配置上传存储。使用一个 `file` 字段，并让 curl 自动设置 multipart boundary。如果本地上传返回 `asset_channel_unavailable`，请把文件放到公网可访问的 HTTPS URL，再使用上一步的 URL 创建方式。

<CodeGroup>
```bash Bash
Expand All @@ -435,7 +456,7 @@ curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/asse

创建响应会包含素材 ID 或 `asset_uri`，例如 `asset://ast_1234567890abcdef1234567890abcdef`。

#### 5. 轮询素材状态并调用 Seedance
#### 6. 轮询素材状态并调用 Seedance

真人素材响应不包含 `available_models`。列出这个真人档案下的素材，直到素材 `status` 变成 `Active`：

Expand Down