> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 列出或搜索项目 > 列出可访问的项目，支持分页、按名称搜索，以及语言和状态筛选。团队访客只能看到自己通过 API 创建的项目。 列出可访问的项目，支持分页、按名称搜索，以及语言和状态筛选。团队访客只能看到自己通过 API 创建的项目。 ```http theme={null} POST https://api.voicecheap.ai/v1/actions/projects_list ``` ## 身份验证和权限 在此请求头中发送 VoiceCheap API 密钥。也支持通过 Authorization: Bearer 发送同一 API 密钥。OAuth 访问令牌仅适用于 MCP，此 REST 端点不接受 OAuth 访问令牌。 所需权限: `projects:read`. 需要有效的付费订阅。权限不会改变团队角色、资源归属、媒体额度或套餐限制。 ## 参数 文本值。 最小长度: 1. 最大长度: 200. 整数值。 最小值: 0. 最大值: 100000. 默认值: 0. 整数值。 最小值: 1. 最大值: 50. 默认值: 20. 文本值。 允许的值: "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "azerbaijani", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "british english", "estonian", "finnish", "french", "french canadian", "galician", "german", "greek", "gujarati", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "irish", "italian", "japanese", "kannada", "kazakh", "khmer", "korean", "lao", "latvian", "lithuanian", "macedonian", "malay", "malayalam", "mandarin", "marathi", "mongolian", "nepali", "norwegian", "persian", "polish", "portuguese", "brazilian portuguese", "pt\_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu". 文本值。 允许的值: "af", "sq", "am", "ar", "hy", "as", "ast", "az", "ba", "eu", "be", "bn", "bs", "br", "bg", "my", "ca", "ceb", "zh", "hr", "cs", "da", "nl", "en", "eo", "at", "et", "fil", "fo", "fi", "fr", "fr-CA", "fy", "ff", "gd", "gl", "lg", "ka", "de", "el", "gu", "ht", "ha", "haw", "he", "hi", "hu", "is", "ig", "ilo", "id", "ia", "ga", "it", "ja", "jv", "kea", "kn", "kk", "km", "kur", "kir", "ko", "lo", "la", "luo", "lv", "lb", "ln", "lt", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mo", "mn", "ne", "no", "nn", "nso", "nya", "oc", "or", "pa", "ps", "fa", "pl", "pt", "ro", "ru", "sa", "sr", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "ss", "sv", "tl", "tg", "ta", "tt", "te", "th", "bo", "tn", "tr", "tk", "ug", "uk", "umb", "ur", "uz", "vi", "cy", "wo", "xh", "yi", "yo", "zu", "cmn", "yue", "en-GB", "en-US", "en-AU", "auto-detect". 文本值。 允许的值: "awaitingProofreading", "translated", "failed". 文本值。 允许的值: "newestFirst", "oldestFirst". 默认值: "newestFirst". 文本值。 最小长度: 1. 最大长度: 200. 匹配模式: `^[^/\\]+$`. 以下 JSON Schema 保留了发现接口公开的确切字段名、嵌套类型、默认值、范围和可接受值。其他跨字段规则列于操作说明中。 ```json theme={null} { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 200 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "targetLanguage": { "type": "string", "enum": [ "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "azerbaijani", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "british english", "estonian", "finnish", "french", "french canadian", "galician", "german", "greek", "gujarati", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "irish", "italian", "japanese", "kannada", "kazakh", "khmer", "korean", "lao", "latvian", "lithuanian", "macedonian", "malay", "malayalam", "mandarin", "marathi", "mongolian", "nepali", "norwegian", "persian", "polish", "portuguese", "brazilian portuguese", "pt_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu" ] }, "originalLanguage": { "type": "string", "enum": [ "af", "sq", "am", "ar", "hy", "as", "ast", "az", "ba", "eu", "be", "bn", "bs", "br", "bg", "my", "ca", "ceb", "zh", "hr", "cs", "da", "nl", "en", "eo", "at", "et", "fil", "fo", "fi", "fr", "fr-CA", "fy", "ff", "gd", "gl", "lg", "ka", "de", "el", "gu", "ht", "ha", "haw", "he", "hi", "hu", "is", "ig", "ilo", "id", "ia", "ga", "it", "ja", "jv", "kea", "kn", "kk", "km", "kur", "kir", "ko", "lo", "la", "luo", "lv", "lb", "ln", "lt", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mo", "mn", "ne", "no", "nn", "nso", "nya", "oc", "or", "pa", "ps", "fa", "pl", "pt", "ro", "ru", "sa", "sr", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "ss", "sv", "tl", "tg", "ta", "tt", "te", "th", "bo", "tn", "tr", "tk", "ug", "uk", "umb", "ur", "uz", "vi", "cy", "wo", "xh", "yi", "yo", "zu", "cmn", "yue", "en-GB", "en-US", "en-AU", "auto-detect" ] }, "status": { "type": "string", "enum": ["awaitingProofreading", "translated", "failed"] }, "sort": { "default": "newestFirst", "type": "string", "enum": ["newestFirst", "oldestFirst"] }, "folderId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\\\]+$" } }, "additionalProperties": false } ``` ## 请求示例 请将示例资源标识符和媒体键替换为账户返回的值。重试同一次修改操作时，请保持请求标识符不变。 ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_list' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"query":"Product","limit":20,"offset":0,"originalLanguage":"fr","targetLanguage":"english","status":"translated","sort":"newestFirst"}' ``` ```javascript JavaScript theme={null} const input = { query: 'Product', limit: 20, offset: 0, originalLanguage: 'fr', targetLanguage: 'english', status: 'translated', sort: 'newestFirst', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_list', { method: 'POST', headers: { 'x-api-key': process.env.VOICECHEAP_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(input), }); const body = await response.json(); if (!response.ok) throw new Error(body.code + ': ' + body.message); console.log(body); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/projects_list", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"query": "Product", "limit": 20, "offset": 0, "originalLanguage": "fr", "targetLanguage": "english", "status": "translated", "sort": "newestFirst"}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## 响应 首次执行成功时返回 HTTP 200，操作结果位于 data 下。重放请求时可能改为返回已保存的请求状态。示例展示了一种支持的响应，并未包含所有可选字段。 返回一页可访问的项目摘要和基于偏移量的分页元数据。 ```json HTTP 200 theme={null} { "data": { "projects": [ { "projectId": "project_launch_2026", "projectName": "Product launch", "originalLanguage": "fr", "targetLanguages": [ "english" ], "duration": 75, "createdAt": 1792152000000, "progressStep": "done", "folderId": null } ], "offset": 0, "limit": 20, "nextOffset": null } } ``` ## 结果字段 | 字段 | 说明 | | - | - | | `data.projects` | 一页公开的项目摘要。 | | `data.offset` | 请求的起始偏移量。 | | `data.limit` | 请求的每页条目数。 | | `data.nextOffset` | 获取的页面已满时为 offset + limit，否则为 null。 | | `data.projects[].duration` | 已存储的时长，以秒为单位。 | | `data.projects[].createdAt` | 项目创建时间，以 Unix 毫秒表示。 | | `data.projects[].folderId` | 文件夹标识符或 null。 | ## 操作说明 * offset 默认为 0，limit 默认为 20（最大为 50），sort 默认为 newestFirst。query 按项目名称搜索；folderId、源语言、目标语言和状态用于筛选列表。 * 返回的项目字段为 projectId、projectName、originalLanguage、targetLanguages、duration、createdAt、progressStep 和 folderId。未存储的可选字段可能被省略；targetLanguages 默认为 \[]，duration 默认为 0，folderId 默认为 null。 * 当底层获取的页面包含 limit 个条目时，会设置 nextOffset；它不是总数，也不证明存在下一个可访问结果。 * 团队访客只能看到该成员在同一团队中通过 API 创建的项目。即使存在 nextOffset，筛选后返回的 projects 数组也可能较短。 * originalLanguage 使用 fr 或 en 等源语言代码（在允许时也可使用 auto-detect）；targetLanguage 使用 english 等受支持的目标语言名称。 ## 用量 每次成功调用消耗一次月度 API/MCP 调用额度。媒体额度和操作本身的生成限额也适用。 ## 错误 | HTTP 状态 | 代码 | 含义或恢复方式 | | - | - | - | | 400 | `CREDENTIAL_IN_QUERY` | 凭证通过 access\_token 或 api\_key 查询参数提供。请在标头中发送凭证。 | | 400 | `VALIDATION_ERROR` | 请根据架构更正输入。无效或不一致的值会在执行前被拒绝。 | | 401 | `API_KEY_EXPIRED` | API 密钥已过期。 | | 401 | `INVALID_API_KEY` | 请提供有效且未过期的 API 密钥。 | | 401 | `INVALID_CREDENTIAL` | Authorization 标头格式错误或与 x-api-key 冲突。 | | 401 | `MISSING_CREDENTIAL` | 未提供可用的请求头凭据，或其长度超过 4096 个字符。 | | 401 | `USER_NOT_FOUND` | 该凭据对应的账户已不存在。 | | 403 | `AMBIGUOUS_TEAM_API_KEY` | 此凭据对应的用户属于多个团队，因此计费上下文不明确。 | | 403 | `INSUFFICIENT_SCOPE` | 请授予全部所需权限，或选择其他凭据。 | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | 无法验证该账户的集成限制。 | | 403 | `SUBSCRIPTION_REQUIRED` | 请使用有效的付费订阅。 | | 403 | `TEAM_OWNER_NOT_FOUND` | 找不到实际生效的团队所有者账户。 | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 请等待月度额度重置，或更改套餐。 | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | 如果提供了 Retry-After，请等待其指定的时间，并采用退避重试。 | | 500 | `INTERNAL_ERROR` | 在决定是否重试修改操作前，请检查已保存的请求状态和资源历史记录。 | | 503 | `SERVER_RESTARTING` | 服务器正在重启。请稍后重试；对于修改操作，请保持请求标识符不变。 | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["projects:read"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.