diff --git a/docs/zh/.translation-manifest.json b/docs/zh/.translation-manifest.json index a3233b1..a18f472 100644 --- a/docs/zh/.translation-manifest.json +++ b/docs/zh/.translation-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-09-02T04:58:04.200Z", + "generatedAt": "2026-09-02T09:12:44.494Z", "pages": { "https://developers.openai.com/api/docs/actions/actions-library.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2152,14 +2152,14 @@ "translatedAt": "2026-08-30T07:35:07.431Z" }, "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/beta/subresources/chatkit/subresources/threads.md", "sourceSha256": "64bff9020158c411886fcbab1fcf8a950e4991caed167aa2272849a0469c5a0c", "sourceUrl": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads.md", "targetPath": "docs/zh/api/reference/resources/beta/subresources/chatkit/subresources/threads.md", - "targetSha256": "0271e21949f3f30c604d077da0b99f33a4d3341e5b148f1ac9136fa0a749baef", - "translatedAt": "2026-08-26T19:48:52.544Z" + "targetSha256": "84a820300a92adb41b433baede57b15bac6b2a5d9cbc5e62afe27bb32e99e836", + "translatedAt": "2026-09-02T08:25:54.931Z" }, "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads/methods/delete.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2482,14 +2482,14 @@ "translatedAt": "2026-09-02T02:12:58.511Z" }, "https://developers.openai.com/api/reference/resources/containers.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/containers.md", "sourceSha256": "578cdf3d87f496668494c6cc604011bbe002a3d672c5828a9b89e9c04240ce57", "sourceUrl": "https://developers.openai.com/api/reference/resources/containers.md", "targetPath": "docs/zh/api/reference/resources/containers.md", - "targetSha256": "8324a669b28d7295976f2fd31ab7c00132168e973d453c74a04e6a61f2c60601", - "translatedAt": "2026-08-26T20:24:21.647Z" + "targetSha256": "83a4cc9a6cb51f7452a7130a45ee41a6ace41c35ee91ddae5a10c200ce2b18ab", + "translatedAt": "2026-09-02T08:27:55.705Z" }, "https://developers.openai.com/api/reference/resources/containers/methods/create.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2642,14 +2642,14 @@ "translatedAt": "2026-08-30T14:46:10.896Z" }, "https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/conversations/subresources/items/methods/list.md", "sourceSha256": "4a3cbebefbf8e605f0eb1f0548bd55c3ac3ebfacb5ca023b1b0a365d8e442bd6", "sourceUrl": "https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list.md", "targetPath": "docs/zh/api/reference/resources/conversations/subresources/items/methods/list.md", - "targetSha256": "cdf5aa9cda9df7c3a219f07e3db6266eb0c9c9dede6e0ca59fc4b6aad2d670e3", - "translatedAt": "2026-08-26T20:30:27.601Z" + "targetSha256": "f8f76f8c19ad6a0c45376dddfc68b26e684fcf47a41d96482836fddfc8fc7510", + "translatedAt": "2026-09-02T08:32:28.987Z" }, "https://developers.openai.com/api/reference/resources/embeddings.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2682,14 +2682,14 @@ "translatedAt": "2026-09-02T03:00:42.446Z" }, "https://developers.openai.com/api/reference/resources/evals/methods/create.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/evals/methods/create.md", "sourceSha256": "56d8236bacf6427f7a0bea707a023f2856f53484471f2af795e43a73c3ee0200", "sourceUrl": "https://developers.openai.com/api/reference/resources/evals/methods/create.md", "targetPath": "docs/zh/api/reference/resources/evals/methods/create.md", - "targetSha256": "74ec13acd71f1bb72e2befe5577c3489e7348c6267a1ad2863004e277449b377", - "translatedAt": "2026-08-26T20:34:22.992Z" + "targetSha256": "7931bc57138e1deff22445be962927db562aa8c6975b513e977e30dc07a22b67", + "translatedAt": "2026-09-02T08:33:36.957Z" }, "https://developers.openai.com/api/reference/resources/evals/methods/delete.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2822,14 +2822,14 @@ "translatedAt": "2026-08-30T14:51:24.795Z" }, "https://developers.openai.com/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md", "sourceSha256": "25d53a572396acd172097d55a60560f440c765d779d8f638731c9b186d071322", "sourceUrl": "https://developers.openai.com/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md", "targetPath": "docs/zh/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md", - "targetSha256": "2b6190ce98700bda6cd06850a39094ba4cc01ce054ae0375b2d52a23f9765df7", - "translatedAt": "2026-08-26T20:38:11.415Z" + "targetSha256": "4900f5abde78ff4c325e90bf6752d5e13f4050c38352774f8ef2bf3f657028f8", + "translatedAt": "2026-09-02T08:35:17.463Z" }, "https://developers.openai.com/api/reference/resources/fine_tuning/subresources/jobs/subresources/checkpoints/methods/list.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2842,44 +2842,44 @@ "translatedAt": "2026-08-30T14:51:37.957Z" }, "https://developers.openai.com/api/reference/resources/graders.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/graders.md", "sourceSha256": "86e6a218b6b890211c2606630b3315f3abbc24715ae2862f46c4f4eb18111f36", "sourceUrl": "https://developers.openai.com/api/reference/resources/graders.md", "targetPath": "docs/zh/api/reference/resources/graders.md", - "targetSha256": "8eb4a5cf659b9796305b8517e600f182f6a3fba7570080eba3dae8fec716bd7d", - "translatedAt": "2026-08-26T20:38:32.028Z" + "targetSha256": "ba7ea38b3037f3c05c4572917bc09874e4cdb6c54fdb55d6c2394a9fbdbeedd3", + "translatedAt": "2026-09-02T08:36:05.057Z" }, "https://developers.openai.com/api/reference/resources/images.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/images.md", "sourceSha256": "c5d5ea6101854a273c62621b323f1b5703d432084d1f508631eb04794ff7caff", "sourceUrl": "https://developers.openai.com/api/reference/resources/images.md", "targetPath": "docs/zh/api/reference/resources/images.md", - "targetSha256": "743ad1f5e5fffe02d494ecb321b505d819a5690e59dc04f310d45a71658d8efd", - "translatedAt": "2026-08-26T20:39:19.572Z" + "targetSha256": "592a21432dcee587330eb6b559489103a0231693e61fb70678c4b9cb288dbe67", + "translatedAt": "2026-09-02T08:38:08.993Z" }, "https://developers.openai.com/api/reference/resources/images/edit-streaming-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/images/edit-streaming-events.md", "sourceSha256": "30c777fbcc444fb6d5deffdb107b0f88b666758a19555cf14a7453954d15ca4b", "sourceUrl": "https://developers.openai.com/api/reference/resources/images/edit-streaming-events.md", "targetPath": "docs/zh/api/reference/resources/images/edit-streaming-events.md", - "targetSha256": "b1058d6ed1354944d027d6cdd293ea315c486adec326461332111ce75a3b3250", - "translatedAt": "2026-08-26T20:39:31.081Z" + "targetSha256": "1a44ee17b441db21025d4d0980bda839404bf0d9a4cf187f3e9c18c71491e2b3", + "translatedAt": "2026-09-02T08:38:33.085Z" }, "https://developers.openai.com/api/reference/resources/images/generation-streaming-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/images/generation-streaming-events.md", "sourceSha256": "32a4e20e3c4672e9e5ff94d2cbfa55e8c57e33dc157aee94b7204bda75e05ee8", "sourceUrl": "https://developers.openai.com/api/reference/resources/images/generation-streaming-events.md", "targetPath": "docs/zh/api/reference/resources/images/generation-streaming-events.md", - "targetSha256": "c5a95d804197595c3158ca1b6fff7284b62a5053eb82bacae96330a10bf02c30", - "translatedAt": "2026-08-26T20:39:40.522Z" + "targetSha256": "c7f507f63deee5f220c0fbc989a15c45f176b2194b1d396e2dcfff9bc5b5dee2", + "translatedAt": "2026-09-02T08:39:03.209Z" }, "https://developers.openai.com/api/reference/resources/images/methods/create_variation.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -2932,14 +2932,14 @@ "translatedAt": "2026-09-02T03:08:48.972Z" }, "https://developers.openai.com/api/reference/resources/moderations.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/moderations.md", "sourceSha256": "d83c307f765ffa16ec832bccbab36582855314e3b9b68e2086359f3474c4269c", "sourceUrl": "https://developers.openai.com/api/reference/resources/moderations.md", "targetPath": "docs/zh/api/reference/resources/moderations.md", - "targetSha256": "b7054c5353b43c7cd0b6877d7a11c5bf6b09d6b583802871de16edcc8a4c8d3e", - "translatedAt": "2026-08-26T20:40:01.150Z" + "targetSha256": "2c66bdade67ef26616f6c571a03276fa3636304f450395fec4cf54bfc89b455d", + "translatedAt": "2026-09-02T08:40:08.892Z" }, "https://developers.openai.com/api/reference/resources/moderations/methods/create.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -3692,24 +3692,24 @@ "translatedAt": "2026-09-01T20:36:44.505Z" }, "https://developers.openai.com/api/reference/resources/realtime/client-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/client-events.md", "sourceSha256": "605aa7022bb4bd0fe6680de790c99e7988b4b513b604776eb4e47bb3aba0645e", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/client-events.md", "targetPath": "docs/zh/api/reference/resources/realtime/client-events.md", - "targetSha256": "6cd003bba963ba55c2ca639be6c21d61f73c6f220a9086d32a46611e35eabe95", - "translatedAt": "2026-08-26T20:52:56.620Z" + "targetSha256": "085ae65ad3441fcb9156817a467e814fad5efac2d23817f2c81bad7cec137dbd", + "translatedAt": "2026-09-02T08:41:58.018Z" }, "https://developers.openai.com/api/reference/resources/realtime/server-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/server-events.md", "sourceSha256": "0258c7367e033d1a8a9a6e224c7ac70047a93f9201cde84a0e0baaccb7fca323", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/server-events.md", "targetPath": "docs/zh/api/reference/resources/realtime/server-events.md", - "targetSha256": "241fc2f250fe377e42a655feb994ed2ec66e693a41e7f68fe178bdcfe3534bcb", - "translatedAt": "2026-08-26T20:54:46.812Z" + "targetSha256": "364c6e5f094a67dcfee07cf85e4f5a3731c32c7bec49e3da73d01c53cc5301ca", + "translatedAt": "2026-09-02T08:48:50.186Z" }, "https://developers.openai.com/api/reference/resources/realtime/subresources/calls.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -3722,14 +3722,14 @@ "translatedAt": "2026-09-01T20:38:26.325Z" }, "https://developers.openai.com/api/reference/resources/realtime/subresources/calls/methods/accept.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/subresources/calls/methods/accept.md", "sourceSha256": "9c0bf3dd49faac57c00c70de3484735bb58c4607a8b7fb128e4fdbfd4df15915", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/subresources/calls/methods/accept.md", "targetPath": "docs/zh/api/reference/resources/realtime/subresources/calls/methods/accept.md", - "targetSha256": "a00455d187001d74acfca463f760313e0ee2ceb949c5b33b8c18bbff37ee371a", - "translatedAt": "2026-08-26T20:56:46.700Z" + "targetSha256": "e789dd11ee6cf4ae9c78fdb60eccf65a050873b4aeb3a1a76027e61c269a1f65", + "translatedAt": "2026-09-02T08:51:58.201Z" }, "https://developers.openai.com/api/reference/resources/realtime/subresources/calls/methods/create.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -3772,44 +3772,44 @@ "translatedAt": "2026-08-31T07:35:59.319Z" }, "https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/subresources/client_secrets.md", "sourceSha256": "dd2592c1a9ec10996e06c117a79ada0dee22b7655b92a7d658c6f16fcaac8876", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets.md", "targetPath": "docs/zh/api/reference/resources/realtime/subresources/client_secrets.md", - "targetSha256": "9556ab19a6c03f16802963b67c7bc9a8bb9bc4686e0190bdb9daf3bdaba62679", - "translatedAt": "2026-08-26T20:57:56.201Z" + "targetSha256": "f165e207c1bea2db9156687e4f77b7121ebfd7353a57d1c0a4485b4adc4d2524", + "translatedAt": "2026-09-02T08:54:57.945Z" }, "https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets/methods/create.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/subresources/client_secrets/methods/create.md", "sourceSha256": "039b7c59f227063d976b724b7bbfa925acef7a16592d3fb916af15665b93ad3c", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets/methods/create.md", "targetPath": "docs/zh/api/reference/resources/realtime/subresources/client_secrets/methods/create.md", - "targetSha256": "34511d0368958c93609c7ac1235250c2b90368f336f62f471d12834106d9834a", - "translatedAt": "2026-08-26T20:59:11.877Z" + "targetSha256": "332a7d83a3e2df8ef5bf84ae5090eeccc39f3be0b6b91b8f06ad3972e931b9be", + "translatedAt": "2026-09-02T08:58:07.185Z" }, "https://developers.openai.com/api/reference/resources/realtime/translation-client-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/translation-client-events.md", "sourceSha256": "da16d0dd867be880fcbc5f7626e4276459f0322d28dd1accc27532be4dd35ca2", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/translation-client-events.md", "targetPath": "docs/zh/api/reference/resources/realtime/translation-client-events.md", - "targetSha256": "72865ee279fbc4146f2b2ec70ea13da67c555d874be2df0b31a3a7a5527ee6ec", - "translatedAt": "2026-08-26T20:59:25.323Z" + "targetSha256": "b79634f6aa8100f4fdf311d083745c36020dd1bed95f4c89b331fb996e846a97", + "translatedAt": "2026-09-02T08:58:44.848Z" }, "https://developers.openai.com/api/reference/resources/realtime/translation-server-events.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/realtime/translation-server-events.md", "sourceSha256": "94785189205cbeae5dcf6bfc3e5749eb97fa2fd7a678206bb6ab8838ecfa3315", "sourceUrl": "https://developers.openai.com/api/reference/resources/realtime/translation-server-events.md", "targetPath": "docs/zh/api/reference/resources/realtime/translation-server-events.md", - "targetSha256": "1182016dd203b8bed17c12fedc511b731a4b57b10ce171d2f8186cf4cf78dfbb", - "translatedAt": "2026-08-26T20:59:44.879Z" + "targetSha256": "8e814022db333c9e400c553d4c909a543db9289430e3eb8ac5bbb58425164656", + "translatedAt": "2026-09-02T08:59:48.221Z" }, "https://developers.openai.com/api/reference/resources/responses.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -3882,14 +3882,14 @@ "translatedAt": "2026-09-02T04:01:37.975Z" }, "https://developers.openai.com/api/reference/resources/responses/subresources/input_items/methods/list.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/responses/subresources/input_items/methods/list.md", "sourceSha256": "d44a14cde6b7a8ce9119308e9c195e0a383897c47f0d7b95ccb640828804c9d2", "sourceUrl": "https://developers.openai.com/api/reference/resources/responses/subresources/input_items/methods/list.md", "targetPath": "docs/zh/api/reference/resources/responses/subresources/input_items/methods/list.md", - "targetSha256": "5baeef0168162a626e8b6f69791f24fee6ef7700cc7b14acf13188f31e501c3b", - "translatedAt": "2026-08-26T21:28:53.491Z" + "targetSha256": "c431fd1f24012ab75a98556dede13e191690a2b99f81a48c4c2c9402a7757282", + "translatedAt": "2026-09-02T09:04:34.700Z" }, "https://developers.openai.com/api/reference/resources/responses/subresources/input_tokens.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -3952,14 +3952,14 @@ "translatedAt": "2026-08-31T07:39:37.426Z" }, "https://developers.openai.com/api/reference/resources/vector_stores.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/vector_stores.md", "sourceSha256": "6760c9314af166a1939d2c297230136f204cf5ec88bb524058ae1bba57e222af", "sourceUrl": "https://developers.openai.com/api/reference/resources/vector_stores.md", "targetPath": "docs/zh/api/reference/resources/vector_stores.md", - "targetSha256": "14af3a59d606323c8d70ca27840ca56054338a610a83513475f95732f5ae6c1a", - "translatedAt": "2026-08-26T21:47:18.028Z" + "targetSha256": "e1465092f337a2950b78d6a8355ad55a586f9ce48054452df381589f7febf0ed", + "translatedAt": "2026-09-02T09:07:51.333Z" }, "https://developers.openai.com/api/reference/resources/vector_stores/methods/create.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -4072,14 +4072,14 @@ "translatedAt": "2026-08-31T07:46:31.073Z" }, "https://developers.openai.com/api/reference/resources/vector_stores/subresources/files.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/vector_stores/subresources/files.md", "sourceSha256": "66e1b5de908a4c7791498f50c7018ec713a56166ec66e9e31fce3d2a235d8580", "sourceUrl": "https://developers.openai.com/api/reference/resources/vector_stores/subresources/files.md", "targetPath": "docs/zh/api/reference/resources/vector_stores/subresources/files.md", - "targetSha256": "1880cec9a3eaa348ec18f21d810a81ebeb3a750756c038d7c0587dd56d03b2f6", - "translatedAt": "2026-08-26T21:47:43.518Z" + "targetSha256": "36b4233990f5fe862c86e6914938a472f2f52783ed780a3037178d2df7f3c886", + "translatedAt": "2026-09-02T09:10:54.862Z" }, "https://developers.openai.com/api/reference/resources/vector_stores/subresources/files/methods/content.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", @@ -4142,14 +4142,14 @@ "translatedAt": "2026-08-31T07:50:25.149Z" }, "https://developers.openai.com/api/reference/resources/videos.md": { - "policySha256": "6e9b1538f41ab5d3db960df19d735ece2c894fe9182904cf1d818170eaeeb7c2", + "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", "reviewStatus": "machine", "sourcePath": "docs/en/api/reference/resources/videos.md", "sourceSha256": "168054916de41d8b661acbf6b476293945b879a5e8da2af99a3e0b967f92cdca", "sourceUrl": "https://developers.openai.com/api/reference/resources/videos.md", "targetPath": "docs/zh/api/reference/resources/videos.md", - "targetSha256": "29935942dfad6161b7667c1e3f6aff2c020c361437223c6502f2182c3958fdcd", - "translatedAt": "2026-08-26T21:48:19.569Z" + "targetSha256": "c9961b4a71943c2e4e77d8ba6ff7b0c1c2617cbad3a660737a38a791a8ed9faa", + "translatedAt": "2026-09-02T09:12:44.494Z" }, "https://developers.openai.com/api/reference/resources/videos/methods/create.md": { "policySha256": "5d41c8a7a73acf25529f1beffa364a03666ea413b7e792e6db794b8f801777b5", diff --git a/docs/zh/api/reference/resources/beta/subresources/chatkit/subresources/threads.md b/docs/zh/api/reference/resources/beta/subresources/chatkit/subresources/threads.md index 6cb76a0..ec0e666 100644 --- a/docs/zh/api/reference/resources/beta/subresources/chatkit/subresources/threads.md +++ b/docs/zh/api/reference/resources/beta/subresources/chatkit/subresources/threads.md @@ -1,18 +1,18 @@ -# 线程 +# Threads -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 获取。 +> 完整的文档索引请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 末尾追加 `.md` 来获取文档页面的 Markdown 版本。 -## 删除 ChatKit 线程 +## 删除 ChatKit 对话线程 -**删除** `/chatkit/threads/{thread_id}` +**delete** `/chatkit/threads/{thread_id}` -删除 ChatKit 线程及其条目和存储的附件。 +删除 ChatKit 会话及其关联条目和已存储的附件。 ### 路径参数 - `thread_id: string` -### 返回 +### 返回值 - `id: string` @@ -24,7 +24,7 @@ - `object: "chatkit.thread.deleted"` - 类型判别器，始终为 `chatkit.thread.deleted`. + 类型鉴别字段，始终为 `chatkit.thread.deleted`. - `"chatkit.thread.deleted"` @@ -47,29 +47,29 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ } ``` -## 列出 ChatKit 线程 +## 列出 ChatKit 会话 **get** `/chatkit/threads` -使用可选分页和用户筛选条件列出 ChatKit 线程。 +列出 ChatKit 会话线程，支持可选的分页和用户筛选。 ### 查询参数 - `after: optional string` - 仅列出在此线程项 ID 之后创建的列表项。默认值为 null，表示第一页。 + 列出在此 thread item ID 之后创建的项目。默认为 null 以获取第一页。 - `before: optional string` - 仅列出在此线程项 ID 之前创建的列表项。默认值为 null，表示最新结果。 + 列出在此 thread item ID 之前创建的项目。默认为 null 以获取最新结果。 - `limit: optional number` - 要返回的最大线程项数量。默认值为 20。 + 返回的 thread item 最大数量。默认为 20。 - `order: optional "asc" or "desc"` - 结果的排序顺序按创建时间。默认值为 `desc`. + 按创建时间排序的结果顺序。默认为 `desc`. - `"asc"` @@ -77,13 +77,13 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `user: optional string` - 筛选属于此用户标识符的线程。默认值为 null 以返回所有用户。 + 筛选属于该用户标识符的线程。默认为 null 表示返回所有用户。 -### 返回 +### 返回值 - `data: array of ChatKitThread` - 项目列表 + 一个项目列表 - `id: string` @@ -95,13 +95,13 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `object: "chatkit.thread"` - 类型判别器，始终为 `chatkit.thread`. + 类型鉴别字段，始终为 `chatkit.thread`. - `"chatkit.thread"` - `status: object { type } or object { reason, type } or object { reason, type }` - 线程的当前状态。默认为 `active` 对于新创建的线程。 + 线程的当前状态。默认为 `active` 适用于新建的线程。 - `Active object { type }` @@ -109,13 +109,13 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `type: "active"` - 状态判别器，始终为 `active`. + 始终为以下值的状态判别字段 `active`. - `"active"` - `Locked object { reason, type }` - 表示线程已被锁定，无法接受新的输入。 + 表示线程已锁定，无法接受新的输入。 - `reason: string or null` @@ -123,7 +123,7 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `type: "locked"` - 状态判别器，始终为 `locked`. + 始终为以下值的状态判别字段 `locked`. - `"locked"` @@ -133,11 +133,11 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `reason: string or null` - 线程关闭的原因。未记录原因时默认为 null。 + 线程被关闭的原因。未记录原因时默认为 null。 - `type: "closed"` - 状态判别器，始终为 `closed`. + 始终为以下值的状态判别字段 `closed`. - `"closed"` @@ -147,23 +147,23 @@ curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - `user: string` - 自由格式字符串，用于标识拥有该线程的最终用户。 + 用于标识拥有该线程的最终用户的自由格式字符串。 - `first_id: string or null` - 列表中第一个项目的 ID。 + 列表中第一项的 ID。 - `has_more: boolean` - 是否还有更多可用项目。 + 是否还有更多项可用。 - `last_id: string or null` - 列表中最后一个项目的 ID。 + 列表中最后一项的 ID。 - `object: "list"` - 返回的对象类型，必须为 `list`. + 返回对象的类型，必须为 `list`. - `"list"` @@ -231,7 +231,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ **get** `/chatkit/threads/{thread_id}/items` -列出属于 ChatKit 线程的项目。 +属于某个 ChatKit 会话线索的列表项。 ### 路径参数 @@ -241,15 +241,15 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `after: optional string` - 列出在此线程项 ID 之后创建的项。首页默认为 null。 + 列出在此 thread item ID 之后创建的项目。默认为 null 以获取第一页。 - `before: optional string` - 列出在此线程项 ID 之前创建的项。最新结果默认为 null。 + 列出在此 thread item ID 之前创建的项目。默认为 null 以获取最新结果。 - `limit: optional number` - 要返回的线程项的最大数量。默认为 20。 + 返回的 thread item 最大数量。默认为 20。 - `order: optional "asc" or "desc"` @@ -259,23 +259,23 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `"desc"` -### 返回 +### 返回值 - `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - 为 ChatKit API 渲染的线程项目分页列表。 + 为 ChatKit API 渲染的线程项的分页列表。 - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - 项目列表 + 一个项目列表 - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - 线程中用户撰写的消息。 + 线程内的用户撰写的消息。 - `id: string` - 线程项目的标识符。 + 线程项的标识符。 - `attachments: array of ChatKitAttachment` @@ -299,7 +299,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "image" or "file"` - 附件判别器。 + 附件判别字段。 - `"image"` @@ -311,7 +311,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `InputText object { text, type }` - 用户贡献到线程的文本块。 + 用户向线程贡献的文本块。 - `text: string` @@ -319,31 +319,31 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "input_text"` - 类型判别器，始终为 `input_text`. + 类型鉴别字段，始终为 `input_text`. - `"input_text"` - `QuotedText object { text, type }` - 用户在其消息中引用的引用片段。 + 用户在消息中引用的引用片段。 - `text: string` - 引用文本内容。 + 引用的文本内容。 - `type: "quoted_text"` - 类型判别器，始终为 `quoted_text`. + 类型鉴别字段，始终为 `quoted_text`. - `"quoted_text"` - `created_at: number` - 项目创建时的 Unix 时间戳（以秒为单位）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `inference_options: object { model, tool_choice } or null` - 应用于消息的推理覆盖。未设置时默认为 null。 + 应用于消息的推理覆盖设置。未设置时默认为 null。 - `model: string or null` @@ -351,7 +351,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `tool_choice: object { id } or null` - 要调用的首选工具。当 ChatKit 应自动选择时默认为 null。 + 首选调用的工具。当 ChatKit 应自动选择时默认为 null。 - `id: string` @@ -359,7 +359,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -373,7 +373,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - 线程中由助手撰写的消息。 + 线程中由 Assistant 创建的消息。 - `id: string` @@ -381,11 +381,11 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `content: array of ChatKitResponseOutputText` - 有序的助手响应片段。 + 有序的 Assistant 响应片段列表。 - `annotations: array of object { source, type } or object { source, type }` - 附加到响应文本的注释的有序列表。 + 附加到响应文本的有序注释列表。 - `File object { source, type }` @@ -401,13 +401,13 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "file"` - 类型判别器，始终为 `file`. + 类型鉴别字段，始终为 `file`. - `"file"` - `type: "file"` - 类型判别器，始终为 `file` 用于此注释。 + 始终为以下值的类型判别字段 `file` 用于此注释。 - `"file"` @@ -421,7 +421,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "url"` - 类型判别器，始终为 `url`. + 类型鉴别字段，始终为 `url`. - `"url"` @@ -431,27 +431,27 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "url"` - 类型判别器，始终为 `url` 用于此注释。 + 始终为以下值的类型判别字段 `url` 用于此注释。 - `"url"` - `text: string` - 智能体生成的文本。 + Assistant 生成的文本。 - `type: "output_text"` - 始终为 `output_text`. + 类型鉴别字段，始终为 `output_text`. - `"output_text"` - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -461,13 +461,13 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "chatkit.assistant_message"` - 始终为 `chatkit.assistant_message`. + 类型鉴别字段，始终为 `chatkit.assistant_message`. - `"chatkit.assistant_message"` - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - 渲染小部件负载的线程项。 + 用于渲染 widget 负载的线程项。 - `id: string` @@ -475,11 +475,11 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -489,17 +489,17 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "chatkit.widget"` - 始终为 `chatkit.widget`. + 类型鉴别字段，始终为 `chatkit.widget`. - `"chatkit.widget"` - `widget: string` - 在 UI 中渲染的序列化小部件负载。 + 在 UI 中渲染的已序列化 widget 负载。 - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - 由智能体发起的客户端工具调用的记录。 + 由 Assistant 发起的客户端工具调用记录。 - `id: string` @@ -507,7 +507,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `arguments: string` - 发送给工具的 JSON 编码参数。 + 发送到该工具的 JSON 编码参数。 - `call_id: string` @@ -515,7 +515,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `name: string` @@ -523,13 +523,13 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `object: "chatkit.thread_item"` - 始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` - `output: string or null` - 从工具捕获的 JSON 编码输出。执行进行中时默认为 null。 + 从该工具捕获的 JSON 编码输出。执行进行中时默认为 null。 - `status: "in_progress" or "completed"` @@ -545,13 +545,13 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "chatkit.client_tool_call"` - 始终为 `chatkit.client_tool_call`. + 类型鉴别字段，始终为 `chatkit.client_tool_call`. - `"chatkit.client_tool_call"` - `ChatKitTask object { id, created_at, heading, 5 more }` - 由 工作流 发出的任务，用于显示进度和状态更新。 + 由 工作流 发出的用于展示进度和状态更新的任务。 - `id: string` @@ -559,7 +559,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `created_at: number` - 创建该项时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `heading: string or null` @@ -567,7 +567,7 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `object: "chatkit.thread_item"` - 始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -589,13 +589,13 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "chatkit.task"` - 始终为 `chatkit.task`. + 类型鉴别字段，始终为 `chatkit.task`. - `"chatkit.task"` - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - 线程中 工作流 任务的集合。 + 线程中分组到一起的工作流任务集合。 - `id: string` @@ -603,17 +603,17 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `created_at: number` - 创建该项时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` - `tasks: array of object { heading, summary, type }` - 组中包含的任务。 + 包含在该分组中的任务。 - `heading: string or null` @@ -637,25 +637,25 @@ curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - `type: "chatkit.task_group"` - 始终为以下值的类型判别器 `chatkit.task_group`. + 类型鉴别字段，始终为 `chatkit.task_group`. - `"chatkit.task_group"` - `first_id: string or null` - 列表中第一个条目的 ID。 + 列表中第一项的 ID。 - `has_more: boolean` - 是否还有更多条目可用。 + 是否还有更多项可用。 - `last_id: string or null` - 列表中最后一个条目的 ID。 + 列表中最后一项的 ID。 - `object: "list"` - 返回的对象类型，必须为 `list`. + 返回对象的类型，必须为 `list`. - `"list"` @@ -750,11 +750,11 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ } ``` -## 检索 ChatKit 线程 +## 检索 ChatKit 会话线程 **get** `/chatkit/threads/{thread_id}` -按其标识符检索一个 ChatKit 线程。 +根据标识符检索 ChatKit 会话线程。 ### 路径参数 @@ -764,7 +764,7 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - `ChatKitThread object { id, created_at, object, 3 more }` - 表示一个 ChatKit 线程及其当前状态。 + 表示一个 ChatKit 会话及其当前状态。 - `id: string` @@ -776,13 +776,13 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - `object: "chatkit.thread"` - 类型判别器，始终为 `chatkit.thread`. + 类型鉴别字段，始终为 `chatkit.thread`. - `"chatkit.thread"` - `status: object { type } or object { reason, type } or object { reason, type }` - 线程的当前状态。默认值为 `active` 对于新创建的线程。 + 线程的当前状态。默认为 `active` 适用于新建的线程。 - `Active object { type }` @@ -790,13 +790,13 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - `type: "active"` - 状态判别器，始终为 `active`. + 始终为以下值的状态判别字段 `active`. - `"active"` - `Locked object { reason, type }` - 表示线程已锁定且无法接受新输入。 + 表示线程已锁定，无法接受新的输入。 - `reason: string or null` @@ -804,7 +804,7 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - `type: "locked"` - 状态判别器，始终为 `locked`. + 始终为以下值的状态判别字段 `locked`. - `"locked"` @@ -818,7 +818,7 @@ curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - `type: "closed"` - 状态判别器，始终为 `closed`. + 始终为以下值的状态判别字段 `closed`. - `"closed"` @@ -899,13 +899,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ } ``` -## 域类型 +## Domain Types -### 聊天会话 +### Chat Session - `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - 表示 ChatKit 会话及其已解析的配置。 + 表示一个 ChatKit 会话及其已解析的配置。 - `id: string` @@ -913,15 +913,15 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `chatkit_configuration: ChatSessionChatKitConfiguration` - 会话的已解析 ChatKit 功能配置。 + 该会话已解析的 ChatKit 功能配置。 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - 自动线程标题设置。 + 自动线程标题偏好设置。 - `enabled: boolean` - 是否启用自动线程标题。 + 是否启用了自动线程标题。 - `file_upload: ChatSessionFileUpload` @@ -929,7 +929,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 指示会话是否启用上传。 + 指示该会话是否启用了上传。 - `max_file_size: number or null` @@ -937,7 +937,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `max_files: number or null` - 会话期间允许的最大上传次数。 + 会话期间允许的最大上传数量。 - `history: ChatSessionHistory` @@ -945,19 +945,19 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 指示会话是否持久化聊天历史记录。 + 指示该会话的聊天历史记录是否被持久化。 - `recent_threads: number or null` - 历史记录视图中显示的先前线程数。当保留所有历史记录时默认为 null。 + 在历史视图里展示的先前线程数量。保留全部历史时默认为 null。 - `client_secret: string` - 用于验证会话请求的临时客户端密钥。 + 用于认证会话请求的临时客户端密钥。 - `expires_at: number` - 会话过期时的 Unix 时间戳（以秒为单位）。 + 会话过期的 Unix 时间戳（单位：秒）。 - `max_requests_per_1_minute: number` @@ -965,7 +965,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.session"` - 类型判别器，始终为 `chatkit.session`. + 类型鉴别字段，始终为 `chatkit.session`. - `"chatkit.session"` @@ -975,7 +975,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `max_requests_per_1_minute: number` - 一分钟窗口内允许的最大请求数。 + 一分钟时间窗口内允许的最大请求数。 - `status: ChatSessionStatus` @@ -997,11 +997,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `id: string` - 工作流的标识符，用于支撑会话。 + 为该会话提供支持的工作流的标识符。 - `state_variables: map[string or boolean or number] or null` - 调用工作流时应用的状态变量键值对。未提供覆盖项时默认为 null。 + 调用该工作流时应用的状态变量键值对。如果未提供覆盖，默认值为 null。 - `string` @@ -1011,17 +1011,17 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `tracing: object { enabled }` - 应用于工作流的追踪设置。 + 应用于该工作流的追踪设置。 - `enabled: boolean` - 指示是否启用追踪。 + 指示是否启用了追踪。 - `version: string or null` - 会话使用的特定工作流版本。使用最新部署时默认为 null。 + 会话所使用的特定工作流版本。使用最新部署时，默认值为 null。 -### 聊天会话自动线程标题 +### 聊天会话自动线程命名 - `ChatSessionAutomaticThreadTitling object { enabled }` @@ -1029,21 +1029,21 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 是否启用自动线程标题。 + 是否启用了自动线程标题。 ### Chat Session ChatKit 配置 - `ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }` - 会话的 ChatKit 配置。 + 该会话的 ChatKit 配置。 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - 自动线程标题设置偏好。 + 自动线程标题偏好设置。 - `enabled: boolean` - 是否启用自动线程标题。 + 是否启用了自动线程标题。 - `file_upload: ChatSessionFileUpload` @@ -1051,7 +1051,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 指示会话是否允许上传。 + 指示该会话是否启用了上传。 - `max_file_size: number or null` @@ -1059,7 +1059,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `max_files: number or null` - 会话期间允许的最大上传次数。 + 会话期间允许的最大上传数量。 - `history: ChatSessionHistory` @@ -1067,59 +1067,59 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 指示会话是否持久保存聊天历史记录。 + 指示该会话的聊天历史记录是否被持久化。 - `recent_threads: number or null` - 历史视图展示的先前线程数量。当保留所有历史记录时默认为 null。 + 在历史视图里展示的先前线程数量。保留全部历史时默认为 null。 -### 聊天会话 ChatKit 配置参数 +### Chat Session ChatKit Configuration Param - `ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }` - ChatKit 行为的可选按会话配置设置。 + ChatKit 行为的可选会话级配置设置。 - `automatic_thread_titling: optional object { enabled }` - 自动线程标题的配置。省略时，自动线程标题默认启用。 + 自动会话标题配置。若省略，则默认启用自动会话标题。 - `enabled: optional boolean` - 启用自动线程标题生成。默认为 true。 + 启用自动会话标题生成。默认值为 true。 - `file_upload: optional object { enabled, max_file_size, max_files }` - 上传启用和限制的配置。省略时，上传默认禁用（max_files 10，max_file_size 512 MB）。 + 上传启用与限制的配置。若省略，则默认禁用上传（max_files 为 10，max_file_size 为 512 MB）。 - `enabled: optional boolean` - 为本次会话启用上传。默认为 false。 + 为此会话启用上传。默认值为 false。 - `max_file_size: optional number` - 每个上传文件的最大大小（以兆字节为单位）。默认为 512 MB，这是允许的最大大小。 + 每个上传文件的最大大小（以 MB 为单位）。默认值为 512 MB，即允许的最大大小。 - `max_files: optional number` - 可上传到会话的最大文件数。默认为 10。 + 会话中可上传文件的最大数量。默认值为 10。 - `history: optional object { enabled, recent_threads }` - 聊天历史保留的配置。省略时，历史默认启用，且 recent_threads 无限制（null）。 + 聊天记录保留配置。若省略，则默认启用历史记录，且对 recent_threads 无限制（null）。 - `enabled: optional boolean` - 允许聊天用户访问之前的 ChatKit 线程。默认为 true。 + 允许聊天用户访问此前的 ChatKit 会话。默认值为 true。 - `recent_threads: optional number` - 用户可访问的最近 ChatKit 线程数。未设置时默认为无限。 + 用户可访问的最近 ChatKit 会话数量。未设置时默认无限制。 -### 聊天会话在参数后过期 +### Chat Session Expires After Param - `ChatSessionExpiresAfterParam object { anchor, seconds }` - 控制会话相对于锚定时间戳何时过期。 + 控制相对于锚点时间戳的会话过期时机。 - `anchor: "created_at"` @@ -1129,7 +1129,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `seconds: number` - 锚点之后会话过期的秒数。 + 在锚点之后多少秒会话过期。 ### 聊天会话文件上传 @@ -1139,39 +1139,39 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `enabled: boolean` - 指示会话是否启用上传功能。 + 指示该会话是否启用了上传。 - `max_file_size: number or null` - 最大上传大小，以兆字节为单位。 + 最大上传大小（以 MB 为单位）。 - `max_files: number or null` - 会话期间允许的最大上传次数。 + 会话期间允许的最大上传数量。 ### 聊天会话历史 - `ChatSessionHistory object { enabled, recent_threads }` - 返回的会话历史记录保留偏好。 + 为该会话返回的历史记录保留偏好。 - `enabled: boolean` - 指示会话是否持久化聊天历史记录。 + 指示该会话的聊天历史记录是否被持久化。 - `recent_threads: number or null` - 历史视图中显示的先前线程数。当保留全部历史记录时，默认为 null。 + 在历史视图里展示的先前线程数量。保留全部历史时默认为 null。 ### 聊天会话速率限制 - `ChatSessionRateLimits object { max_requests_per_1_minute }` - 会话的每分钟活跃请求限制。 + 会话的每分钟活跃请求上限。 - `max_requests_per_1_minute: number` - 一分钟窗口内允许的最大请求数。 + 一分钟时间窗口内允许的最大请求数。 ### 聊天会话速率限制参数 @@ -1197,15 +1197,15 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `ChatSessionWorkflowParam object { id, state_variables, tracing, version }` - 应用于聊天会话的工作流引用与覆盖设置。 + 应用于聊天会话的工作流引用和覆盖。 - `id: string` - 会话所调用工作流的标识符。 + 会话调用的工作流标识符。 - `state_variables: optional map[string or boolean or number]` - 转发至工作流的状态变量。键最多可包含 64 个字符，值必须为原始类型，映射默认为空对象。 + 转发给工作流的状态变量。键最长可达 64 个字符，值必须为基本类型，且该映射默认为空对象。 - `string` @@ -1215,7 +1215,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `tracing: optional object { enabled }` - 工作流调用的可选追踪覆盖设置。省略时，默认启用追踪。 + 针对工作流调用的可选追踪覆盖。未指定时，追踪默认启用。 - `enabled: optional boolean` @@ -1223,13 +1223,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `version: optional string` - 要运行的特定工作流版本。默认为最新部署版本。 + 要运行的特定工作流版本。默认为最新部署的版本。 ### ChatKit 附件 - `ChatKitAttachment object { id, mime_type, name, 2 more }` - 线程项目上包含的附件元数据。 + 在线程项上包含的附件元数据。 - `id: string` @@ -1249,21 +1249,21 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "image" or "file"` - 附件区分符。 + 附件判别字段。 - `"image"` - `"file"` -### ChatKit 响应输出文本 +### ChatKit Response Output Text - `ChatKitResponseOutputText object { annotations, text, type }` - 助手响应文本，附带可选的注释。 + Assistant 回复文本，可附带可选的注解。 - `annotations: array of object { source, type } or object { source, type }` - 附加到响应文本的注释的有序列表。 + 附加到响应文本的有序注释列表。 - `File object { source, type }` @@ -1279,13 +1279,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "file"` - 类型判别器，始终为 `file`. + 类型鉴别字段，始终为 `file`. - `"file"` - `type: "file"` - 类型判别器，始终为 `file` 用于此注释。 + 始终为以下值的类型判别字段 `file` 用于此注释。 - `"file"` @@ -1299,7 +1299,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "url"` - 类型判别器，始终为 `url`. + 类型鉴别字段，始终为 `url`. - `"url"` @@ -1309,17 +1309,17 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "url"` - 类型判别器，始终为 `url` 用于此注释。 + 始终为以下值的类型判别字段 `url` 用于此注释。 - `"url"` - `text: string` - 助手生成的文本。 + Assistant 生成的文本。 - `type: "output_text"` - 类型判别器，始终为 `output_text`. + 类型鉴别字段，始终为 `output_text`. - `"output_text"` @@ -1327,7 +1327,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `ChatKitThread object { id, created_at, object, 3 more }` - 表示一个 ChatKit 线程及其当前状态。 + 表示一个 ChatKit 会话及其当前状态。 - `id: string` @@ -1339,13 +1339,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.thread"` - 类型判别器，始终为 `chatkit.thread`. + 类型鉴别字段，始终为 `chatkit.thread`. - `"chatkit.thread"` - `status: object { type } or object { reason, type } or object { reason, type }` - 线程的当前状态。默认为 `active` 对于新创建的线程。 + 线程的当前状态。默认为 `active` 适用于新建的线程。 - `Active object { type }` @@ -1353,7 +1353,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "active"` - 状态判别器，始终为 `active`. + 始终为以下值的状态判别字段 `active`. - `"active"` @@ -1367,7 +1367,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "locked"` - 状态判别器，始终为 `locked`. + 始终为以下值的状态判别字段 `locked`. - `"locked"` @@ -1381,7 +1381,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "closed"` - 状态判别器，始终为 `closed`. + 始终为以下值的状态判别字段 `closed`. - `"closed"` @@ -1393,11 +1393,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ 用于标识拥有该线程的最终用户的自由格式字符串。 -### ChatKit 线程助手消息项 +### ChatKit Thread Assistant Message Item - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - 线程中由助手撰写的消息。 + 线程中由 Assistant 创建的消息。 - `id: string` @@ -1405,77 +1405,77 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `content: array of ChatKitResponseOutputText` - 有序的助手响应片段。 + 有序的 Assistant 响应片段列表。 - `annotations: array of object { source, type } or object { source, type }` - 附加到响应文本的注解的有序列表。 + 附加到响应文本的有序注释列表。 - `File object { source, type }` - 引用已上传文件的注解。 + 引用已上传文件的注释。 - `source: object { filename, type }` - 注解引用的文件附件。 + 注释引用的文件附件。 - `filename: string` - 注解引用的文件名。 + 注释引用的文件名。 - `type: "file"` - 类型判别器，始终为 `file`. + 类型鉴别字段，始终为 `file`. - `"file"` - `type: "file"` - 类型判别器，始终为 `file` 用于此注解。 + 始终为以下值的类型判别字段 `file` 用于此注释。 - `"file"` - `URL object { source, type }` - 引用 URL 的注解。 + 引用 URL 的注释。 - `source: object { type, url }` - 注解引用的 URL。 + 注释引用的 URL。 - `type: "url"` - 类型判别器，始终为 `url`. + 类型鉴别字段，始终为 `url`. - `"url"` - `url: string` - 注解引用的 URL。 + 注释引用的 URL。 - `type: "url"` - 类型判别器，始终为 `url` 用于此注解。 + 始终为以下值的类型判别字段 `url` 用于此注释。 - `"url"` - `text: string` - 助手生成的文本。 + Assistant 生成的文本。 - `type: "output_text"` - 类型判别器，始终为 `output_text`. + 类型鉴别字段，始终为 `output_text`. - `"output_text"` - `created_at: number` - 项创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1485,27 +1485,27 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.assistant_message"` - 类型判别器，始终为 `chatkit.assistant_message`. + 类型鉴别字段，始终为 `chatkit.assistant_message`. - `"chatkit.assistant_message"` -### ChatKit 线程项目列表 +### ChatKit Thread Item List - `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - 为 ChatKit API 渲染的线程条目分页列表。 + 为 ChatKit API 渲染的线程项的分页列表。 - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - 条目列表 + 一个项目列表 - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - 线程中用户撰写的消息。 + 线程内的用户撰写的消息。 - `id: string` - 线程条目的标识符。 + 线程项的标识符。 - `attachments: array of ChatKitAttachment` @@ -1529,7 +1529,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "image" or "file"` - 附件判别器。 + 附件判别字段。 - `"image"` @@ -1541,7 +1541,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `InputText object { text, type }` - 用户添加到线程中的文本块。 + 用户向线程贡献的文本块。 - `text: string` @@ -1549,13 +1549,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "input_text"` - 类型判别器，始终为 `input_text`. + 类型鉴别字段，始终为 `input_text`. - `"input_text"` - `QuotedText object { text, type }` - 用户在其消息中引用的引用片段。 + 用户在消息中引用的引用片段。 - `text: string` @@ -1563,17 +1563,17 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "quoted_text"` - 类型判别器，始终为 `quoted_text`. + 类型鉴别字段，始终为 `quoted_text`. - `"quoted_text"` - `created_at: number` - 条目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `inference_options: object { model, tool_choice } or null` - 应用于消息的推断覆盖。未设置时默认为 null。 + 应用于消息的推理覆盖设置。未设置时默认为 null。 - `model: string or null` @@ -1581,7 +1581,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `tool_choice: object { id } or null` - 要调用的首选工具。当 ChatKit 应自动选择时，默认为 null。 + 首选调用的工具。当 ChatKit 应自动选择时默认为 null。 - `id: string` @@ -1589,7 +1589,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1603,7 +1603,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - 线程中由助手编写的消息。 + 线程中由 Assistant 创建的消息。 - `id: string` @@ -1611,11 +1611,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `content: array of ChatKitResponseOutputText` - 有序的助手响应片段。 + 有序的 Assistant 响应片段列表。 - `annotations: array of object { source, type } or object { source, type }` - 附加到响应文本的注释的有序列表。 + 附加到响应文本的有序注释列表。 - `File object { source, type }` @@ -1631,13 +1631,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "file"` - 类型判别器，始终为 `file`. + 类型鉴别字段，始终为 `file`. - `"file"` - `type: "file"` - 类型判别器，始终为 `file` 此注释的。 + 始终为以下值的类型判别字段 `file` 用于此注释。 - `"file"` @@ -1651,7 +1651,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "url"` - 类型判别器，始终为 `url`. + 类型鉴别字段，始终为 `url`. - `"url"` @@ -1661,27 +1661,27 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "url"` - 类型判别器，始终为 `url` 此注释的。 + 始终为以下值的类型判别字段 `url` 用于此注释。 - `"url"` - `text: string` - 智能体生成的文本。 + Assistant 生成的文本。 - `type: "output_text"` - 类型判别器，始终为 `output_text`. + 类型鉴别字段，始终为 `output_text`. - `"output_text"` - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1691,13 +1691,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.assistant_message"` - 类型判别器，始终为 `chatkit.assistant_message`. + 类型鉴别字段，始终为 `chatkit.assistant_message`. - `"chatkit.assistant_message"` - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - 渲染小部件负载的线程项。 + 用于渲染 widget 负载的线程项。 - `id: string` @@ -1705,11 +1705,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1719,17 +1719,17 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.widget"` - 类型判别器，始终为 `chatkit.widget`. + 类型鉴别字段，始终为 `chatkit.widget`. - `"chatkit.widget"` - `widget: string` - 在 UI 中渲染的序列化小部件负载。 + 在 UI 中渲染的已序列化 widget 负载。 - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - 智能体发起的客户端工具调用的记录。 + 由 Assistant 发起的客户端工具调用记录。 - `id: string` @@ -1737,7 +1737,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `arguments: string` - 发送给工具的 JSON 编码参数。 + 发送到该工具的 JSON 编码参数。 - `call_id: string` @@ -1745,7 +1745,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `created_at: number` - 项目创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `name: string` @@ -1753,13 +1753,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` - `output: string or null` - 从工具捕获的 JSON 编码输出。执行进行中时默认为 null。 + 从该工具捕获的 JSON 编码输出。执行进行中时默认为 null。 - `status: "in_progress" or "completed"` @@ -1775,13 +1775,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.client_tool_call"` - 类型判别器，始终为 `chatkit.client_tool_call`. + 类型鉴别字段，始终为 `chatkit.client_tool_call`. - `"chatkit.client_tool_call"` - `ChatKitTask object { id, created_at, heading, 5 more }` - 工作流发出的任务，用于显示进度和状态更新。 + 由 工作流 发出的用于展示进度和状态更新的任务。 - `id: string` @@ -1789,7 +1789,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `created_at: number` - 项目创建时的 Unix 时间戳（以秒为单位）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `heading: string or null` @@ -1797,7 +1797,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1819,13 +1819,13 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.task"` - 类型判别器，始终为 `chatkit.task`. + 类型鉴别字段，始终为 `chatkit.task`. - `"chatkit.task"` - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - 工作流任务在线程中分组的集合。 + 线程中分组到一起的工作流任务集合。 - `id: string` @@ -1833,17 +1833,17 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `created_at: number` - 项目创建时的 Unix 时间戳（以秒为单位）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` - `tasks: array of object { heading, summary, type }` - 组中包含的任务。 + 包含在该分组中的任务。 - `heading: string or null` @@ -1867,33 +1867,33 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.task_group"` - 始终为 `chatkit.task_group`. + 类型鉴别字段，始终为 `chatkit.task_group`. - `"chatkit.task_group"` - `first_id: string or null` - 列表中第一个项目的 ID。 + 列表中第一项的 ID。 - `has_more: boolean` - 是否还有更多项目可用。 + 是否还有更多项可用。 - `last_id: string or null` - 列表中最后一个项目的 ID。 + 列表中最后一项的 ID。 - `object: "list"` - 返回的对象类型，必须为 `list`. + 返回对象的类型，必须为 `list`. - `"list"` -### ChatKit 线程用户消息条目 +### ChatKit Thread User Message Item - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - 线程中用户撰写的消息。 + 线程内的用户撰写的消息。 - `id: string` @@ -1921,7 +1921,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "image" or "file"` - 附件判别器。 + 附件判别字段。 - `"image"` @@ -1933,7 +1933,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `InputText object { text, type }` - 用户贡献到线程的文本块。 + 用户向线程贡献的文本块。 - `text: string` @@ -1941,31 +1941,31 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "input_text"` - 类型判别器，始终为 `input_text`. + 类型鉴别字段，始终为 `input_text`. - `"input_text"` - `QuotedText object { text, type }` - 用户在其消息中引用的引用片段。 + 用户在消息中引用的引用片段。 - `text: string` - 引用文本内容。 + 引用的文本内容。 - `type: "quoted_text"` - 类型判别器，始终为 `quoted_text`. + 类型鉴别字段，始终为 `quoted_text`. - `"quoted_text"` - `created_at: number` - 项创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `inference_options: object { model, tool_choice } or null` - 应用于消息的推理覆盖。未设置时默认为 null。 + 应用于消息的推理覆盖设置。未设置时默认为 null。 - `model: string or null` @@ -1981,7 +1981,7 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `object: "chatkit.thread_item"` - 始终存在的类型判别器 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -1993,11 +1993,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `"chatkit.user_message"` -### ChatKit 组件项 +### ChatKit Widget Item - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - 渲染小组件负载的线程项。 + 用于渲染 widget 负载的线程项。 - `id: string` @@ -2005,11 +2005,11 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `created_at: number` - 项创建时的 Unix 时间戳（秒）。 + 项创建时的 Unix 时间戳（以秒为单位）。 - `object: "chatkit.thread_item"` - 类型判别器，始终为 `chatkit.thread_item`. + 类型鉴别字段，始终为 `chatkit.thread_item`. - `"chatkit.thread_item"` @@ -2019,19 +2019,19 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `type: "chatkit.widget"` - 类型判别器，始终为 `chatkit.widget`. + 类型鉴别字段，始终为 `chatkit.widget`. - `"chatkit.widget"` - `widget: string` - 在 UI 中渲染的序列化小组件负载。 + 在 UI 中渲染的已序列化 widget 负载。 -### 线程删除响应 +### Thread Delete Response - `ThreadDeleteResponse object { id, deleted, object }` - 删除线程后返回的确认负载。 + 删除线程后返回的确认载荷。 - `id: string` @@ -2039,10 +2039,10 @@ curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - `deleted: boolean` - 指示线程已被删除。 + 表示该线程已被删除。 - `object: "chatkit.thread.deleted"` - 始终为“thread_deleted”的类型判别器。 `chatkit.thread.deleted`. + 类型鉴别字段，始终为 `chatkit.thread.deleted`. - `"chatkit.thread.deleted"` diff --git a/docs/zh/api/reference/resources/containers.md b/docs/zh/api/reference/resources/containers.md index 99b7b7b..7829428 100644 --- a/docs/zh/api/reference/resources/containers.md +++ b/docs/zh/api/reference/resources/containers.md @@ -1,6 +1,6 @@ -# 容器 +# Containers -> 如需查看完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整的文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾追加 `.md` 即可获取 Markdown 版本的文档页面。 ## 创建容器 @@ -8,7 +8,7 @@ 创建容器 -### 请求体参数 +### Body 参数 - `name: string` @@ -16,11 +16,11 @@ - `expires_after: optional object { anchor, minutes }` - 相对于“锚点”时间的容器过期时间（秒）。 + 相对“anchor”时间的容器过期时间（以秒为单位）。 - `anchor: "last_active_at"` - 过期时间的时间锚点。目前仅支持“last_active_at”。 + 过期时间的时间锚点。目前仅支持 'last_active_at'。 - `"last_active_at"` @@ -32,7 +32,7 @@ - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 容器的可选内存限制。默认为“1g”。 + 容器的可选内存限制。默认为 "1g"。 - `"1g"` @@ -58,7 +58,7 @@ - `allowed_domains: array of string` - 当类型为时的允许域列表 `allowlist`. + 当 type 为 `allowlist`. - `type: "allowlist"` @@ -68,23 +68,23 @@ - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - 用于允许列表域的可选域范围密钥。 + 针对白名单域的可选域范围密钥。 - `domain: string` - 与密钥关联的域。 + 与该密钥关联的域。 - `name: string` - 要为域注入的密钥名称。 + 为该域注入的密钥名称。 - `value: string` - 要为域注入的密钥值。 + 为该域注入的密钥值。 - `skills: optional array of SkillReference or InlineSkill` - 按 ID 或内联数据引用的可选技能列表。 + 通过 ID 引用或内联数据的可选技能列表。 - `SkillReference object { skill_id, type, version }` @@ -94,13 +94,13 @@ - `type: "skill_reference"` - 引用使用 /v1/skills 端点创建的技能。 + 引用通过 /v1/skills 端点创建的技能。 - `"skill_reference"` - `version: optional string` - 可选的技能版本。使用正整数或“latest”。省略时使用默认值。 + 可选的技能版本。使用正整数或 'latest'。省略以使用默认值。 - `InlineSkill object { description, name, source, type }` @@ -118,7 +118,7 @@ - `data: string` - Base64 编码的技能 zip 包。 + 经过 Base64 编码的技能 zip 包。 - `media_type: "application/zip"` @@ -128,17 +128,17 @@ - `type: "base64"` - 内联技能来源的类型。必须为 `base64`. + 内联技能源的类型。必须为 `base64`. - `"base64"` - `type: "inline"` - 定义此请求的内联技能。 + 为本次请求定义一个内联技能。 - `"inline"` -### 返回 +### Returns - `id: string` @@ -158,13 +158,13 @@ - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -174,11 +174,11 @@ - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -206,7 +206,7 @@ - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. ### 示例 @@ -294,9 +294,9 @@ curl https://api.openai.com/v1/containers \ ## 删除容器 -**删除** `/containers/{container_id}` +**delete** `/containers/{container_id}` -删除容器 +Delete Container ### 路径参数 @@ -337,11 +337,11 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo 以获取列表的下一页。 + 用于分页的光标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发起列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo 以获取列表的下一页。 - `limit: optional number` - 返回对象数量的限制。限制范围在 1 到 100 之间，默认值为 20。 + 要返回的对象数量上限。限制范围为 1 到 100，默认为 20。 - `name: optional string` @@ -349,13 +349,13 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `order: optional "asc" or "desc"` - 按对象的 `created_at` 时间戳排序。 `asc` 用于升序， `desc` 用于降序。 + 按对象的 `created_at` 时间戳排序。 `asc` 表示升序， `desc` 表示降序。 - `"asc"` - `"desc"` -### 返回 +### Returns - `data: array of object { id, created_at, name, 6 more }` @@ -379,13 +379,13 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -395,11 +395,11 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -427,7 +427,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. - `first_id: string` @@ -435,7 +435,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `has_more: boolean` - 是否还有更多可用容器。 + 是否还有更多容器可用。 - `last_id: string` @@ -443,7 +443,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `object: "list"` - 返回对象的类型，必须为 'list'。 + 返回的对象类型，必须为 'list'。 - `"list"` @@ -523,13 +523,13 @@ curl https://api.openai.com/v1/containers \ **get** `/containers/{container_id}` -检索容器 +Retrieve Container ### 路径参数 - `container_id: string` -### 返回 +### Returns - `id: string` @@ -549,13 +549,13 @@ curl https://api.openai.com/v1/containers \ - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -565,11 +565,11 @@ curl https://api.openai.com/v1/containers \ - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -597,7 +597,7 @@ curl https://api.openai.com/v1/containers \ - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. ### 示例 @@ -655,9 +655,9 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 } ``` -## 域类型 +## Domain Types -### 容器创建响应 +### Container Create Response - `ContainerCreateResponse object { id, created_at, name, 6 more }` @@ -679,13 +679,13 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -695,11 +695,11 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -727,9 +727,9 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. -### 容器列表响应 +### Container List Response - `ContainerListResponse object { id, created_at, name, 6 more }` @@ -751,13 +751,13 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -767,11 +767,11 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -799,9 +799,9 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. -### 容器检索响应 +### Container Retrieve Response - `ContainerRetrieveResponse object { id, created_at, name, 6 more }` @@ -823,13 +823,13 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `status: string` - 容器的状态（例如，active、deleted）。 + 容器的状态（例如 active、deleted）。 - `expires_after: optional object { anchor, minutes }` - 容器将在此时间段后过期。 - 锚点是过期时间的参考点。 - 分钟数是指锚点之后、容器过期之前的分钟数。 + 容器在此时间周期后将过期。 + anchor 是过期时间的参考点。 + minutes 是 anchor 之后到容器过期之前的分钟数。 - `anchor: optional "last_active_at"` @@ -839,11 +839,11 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `minutes: optional number` - 锚点之后、容器过期之前的分钟数。 + anchor 之后到容器过期之前的分钟数。 - `last_active_at: optional number` - 容器最后一次活动时的 Unix 时间戳（以秒为单位）。 + 容器最近一次活跃时的 Unix 时间戳（以秒为单位）。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` @@ -871,33 +871,33 @@ curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a0 - `allowed_domains: optional array of string` - 允许的出站域名，当 `type` 为 `allowlist`. + 当 network_policy.mode 为 `type` 时允许的出站域名 `allowlist`. -# 文件 +# Files -## 创建容器文件 +## Create container file **post** `/containers/{container_id}/files` 创建容器文件 -你可以发送包含原始文件内容的 multipart/form-data 请求，也可以发送包含文件 ID 的 JSON 请求。 +你可以发送包含原始文件内容的 multipart/form-data 请求，或发送包含文件 ID 的 JSON 请求。 ### 路径参数 - `container_id: string` -### 请求体参数 +### Body 参数 - `file: optional string` - 要上传的 File 对象（而非文件名）。 + 要上传的 File 对象（非文件名）。 - `file_id: optional string` 要创建的文件的名称。 -### 返回 +### Returns - `id: string` @@ -974,7 +974,7 @@ curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e0 ## 删除容器文件 -**删除** `/containers/{container_id}/files/{file_id}` +**delete** `/containers/{container_id}/files/{file_id}` 删除容器文件 @@ -1013,7 +1013,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 **get** `/containers/{container_id}/files` -列出容器文件 +列出 Container 文件 ### 路径参数 @@ -1023,21 +1023,21 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo 以获取列表的下一页。 + 用于分页的光标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发起列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo 以获取列表的下一页。 - `limit: optional number` - 返回对象数量的限制。限制范围在 1 到 100 之间，默认值为 20。 + 要返回的对象数量上限。限制范围为 1 到 100，默认为 20。 - `order: optional "asc" or "desc"` - 按对象的 `created_at` 时间戳排序。 `asc` 用于升序， `desc` 用于降序。 + 按对象的 `created_at` 时间戳排序。 `asc` 表示升序， `desc` 表示降序。 - `"asc"` - `"desc"` -### 返回 +### Returns - `data: array of object { id, bytes, container_id, 4 more }` @@ -1077,7 +1077,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `has_more: boolean` - 是否还有更多可用文件。 + 是否有更多文件可用。 - `last_id: string` @@ -1085,7 +1085,7 @@ curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2 - `object: "list"` - 返回对象的类型，必须为 'list'。 + 返回的对象类型，必须为 'list'。 - `"list"` @@ -1159,7 +1159,7 @@ curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e0 - `file_id: string` -### 返回 +### Returns - `id: string` @@ -1231,7 +1231,7 @@ curl https://api.openai.com/v1/containers/container_123/files/file_456 \ } ``` -## 域类型 +## Domain Types ### 文件创建响应 @@ -1335,7 +1335,7 @@ curl https://api.openai.com/v1/containers/container_123/files/file_456 \ **get** `/containers/{container_id}/files/{file_id}/content` -检索容器文件内容 +Retrieve Container File Content ### 路径参数 diff --git a/docs/zh/api/reference/resources/conversations/subresources/items/methods/list.md b/docs/zh/api/reference/resources/conversations/subresources/items/methods/list.md index b279b1e..87c83d8 100644 --- a/docs/zh/api/reference/resources/conversations/subresources/items/methods/list.md +++ b/docs/zh/api/reference/resources/conversations/subresources/items/methods/list.md @@ -1,10 +1,10 @@ -> 有关完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 完整的文档索引请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 后追加 `.md` 来获取文档页面的 Markdown 版本。 ## 列表项 **get** `/conversations/{conversation_id}/items` -列出具有指定 ID 的会话中的所有项目。 +列出具有指定 ID 的会话的所有条目。 ### 路径参数 @@ -14,19 +14,19 @@ - `after: optional string` - 用于分页的条目 ID，用于列出其后的条目。 + 用于分页的项 ID，列出在该项之后的条目。 - `include: optional array of ResponseIncludable` - 指定要在模型响应中包含的额外输出数据。当前支持的值有： + 指定要在模型响应中包含的其他输出数据。目前支持的值包括： - - `web_search_call.action.sources`：包含 网页搜索工具调用的来源。 - - `code_interpreter_call.outputs`：包含代码解释器工具调用项中 Python 代码执行的输出。 - - `computer_call_output.output.image_url`：包含计算机调用输出中的图像 URL。 - - `file_search_call.results`：包含 文件搜索工具调用的搜索结果。 - - `message.input_image.image_url`：包含输入消息中的图像 URL。 - - `message.output_text.logprobs`：包含助手消息的 logprobs。 - - `reasoning.encrypted_content`：在推理项输出中包含推理令牌的加密版本。这允许在使用 Responses API 无状态时（如当 `store` 参数设置为 `false`，或组织已加入零数据保留计划时），在多轮对话中使用推理项。 + - `web_search_call.action.sources`：包含 网页搜索 工具调用的来源。 + - `code_interpreter_call.outputs`：在代码解释器工具调用项中包含 Python 代码执行的输出。 + - `computer_call_output.output.image_url`：包含来自计算机调用输出中的图片 URL。 + - `file_search_call.results`：包含 文件搜索 工具调用的搜索结果。 + - `message.input_image.image_url`：包含来自输入消息中的图片 URL。 + - `message.output_text.logprobs`：在助手消息中包含 logprobs。 + - `reasoning.encrypted_content`：在推理项输出中包含加密版本的推理 token。这使得在使用 Responses API 时（例如当 `store` 参数设置为 `false`，或组织已加入零数据保留计划时）能够在多轮对话中使用推理项。 - `"file_search_call.results"` @@ -46,7 +46,7 @@ - `limit: optional number` - 返回对象数量的限制。限制范围可在 + 返回对象数量的上限。范围介于 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` @@ -60,15 +60,15 @@ - `"desc"` -### 返回 +### Returns - `ConversationItemList object { data, first_id, has_more, 2 more }` - 会话（Conversation）项的列表。 + 对话项的列表。 - `data: array of ConversationItem` - 会话（conversation）项的列表。 + 对话项的列表。 - `Message object { id, content, role, 3 more }` @@ -84,11 +84,11 @@ - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入到模型的文本。 + 发送给模型的文本输入。 - `text: string` - 输入到模型的文本。 + 发送给模型的文本输入。 - `type: "input_text"` @@ -98,7 +98,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会舍入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求中继承其 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -108,7 +108,7 @@ - `ResponseOutputText object { annotations, logprobs, text, type }` - 来自模型的文本输出。 + 模型输出的文本。 - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` @@ -124,11 +124,11 @@ - `filename: string` - 所引用文件的文件名。 + 被引用文件的文件名。 - `index: number` - 文件在文件列表中的索引。 + 该文件在文件列表中的索引。 - `type: "file_citation"` @@ -138,19 +138,19 @@ - `URLCitation object { end_index, start_index, title, 2 more }` - 用于生成模型响应的网络资源的引用。 + 用于生成模型响应的网页资源引用。 - `end_index: number` - URL 引用在消息中最后一个字符的索引。 + URL 引用在消息中的最后一个字符的索引。 - `start_index: number` - 消息中 URL 引用的首字符索引。 + 消息中 URL 引用的起始字符索引。 - `title: string` - Web 资源的标题。 + 网页资源的标题。 - `type: "url_citation"` @@ -160,11 +160,11 @@ - `url: string` - Web 资源的 URL。 + 网页资源的 URL。 - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - 用于生成模型响应的容器文件的引用。 + 用于生成模型响应的容器文件引用。 - `container_id: string` @@ -172,7 +172,7 @@ - `end_index: number` - 消息中容器文件引用的最后一个字符的索引。 + 消息中容器文件引用的结束字符索引。 - `file_id: string` @@ -180,11 +180,11 @@ - `filename: string` - 所引用的容器文件的文件名。 + 被引用容器文件的文件名。 - `start_index: number` - 消息中容器文件引用的首字符索引。 + 消息中容器文件引用的起始字符索引。 - `type: "container_file_citation"` @@ -194,7 +194,7 @@ - `FilePath object { file_id, index, type }` - 文件的路径。 + 文件路径。 - `file_id: string` @@ -202,7 +202,7 @@ - `index: number` - 文件在文件列表中的索引。 + 该文件在文件列表中的索引。 - `type: "file_path"` @@ -228,7 +228,7 @@ - `text: string` - 模型的文本输出。 + 模型输出的文本。 - `type: "output_text"` @@ -248,11 +248,11 @@ - `SummaryTextContent object { text, type }` - 模型的摘要文本。 + 模型输出的摘要文本。 - `text: string` - 模型迄今为止的推理输出的摘要。 + 模型截至目前的推理输出摘要。 - `type: "summary_text"` @@ -262,11 +262,11 @@ - `ReasoningText object { text, type }` - 模型的推理文本。 + 模型输出的推理文本。 - `text: string` - 模型的推理文本。 + 模型输出的推理文本。 - `type: "reasoning_text"` @@ -276,15 +276,15 @@ - `ResponseOutputRefusal object { refusal, type }` - 模型的拒绝回复。 + 模型返回的拒绝内容。 - `refusal: string` - 模型拒绝回复的说明。 + 模型给出的拒绝解释。 - `type: "refusal"` - 拒绝回复的类型。始终为 `refusal`. + 拒绝内容的类型。始终为 `refusal`. - `"refusal"` @@ -294,7 +294,7 @@ - `detail: ImageDetail` - 发送给模型的图像的细节级别。取值为 `high`, `low`, `auto`，或 `original`。默认值为 `auto`. + 发送给模型的图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。之一。默认为 `auto`. - `"low"` @@ -312,15 +312,15 @@ - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件的 ID。 - `image_url: optional string or null` - 要发送给模型的图像的 URL。可以是完全限定的 URL，也可以是数据 URL 中的 base64 编码图像。 + 发送给模型的图像的 URL。完整的 URL 或 data URL 中的 base64 编码图像。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会舍入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求中继承其 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -330,29 +330,29 @@ - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` - 计算机的截图。 + 一张计算机屏幕截图。 - `detail: ImageDetail` - 要发送给模型的截图图像的细节级别。取值为 `high`, `low`, `auto`，或 `original`。默认值为 `auto`. + 发送给模型的屏幕截图图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。之一。默认为 `auto`. - `file_id: string or null` - 包含截图的上传文件的标识符。 + 包含屏幕截图的上传文件的标识符。 - `image_url: string or null` - 截图图像的 URL。 + 屏幕截图图像的 URL。 - `type: "computer_screenshot"` - 指定事件类型。对于计算机截图，此属性始终设置为 `computer_screenshot`. + 指定事件类型。对于计算机屏幕截图，此属性始终设置为 `computer_screenshot`. - `"computer_screenshot"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会舍入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求中继承其 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -372,7 +372,7 @@ - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 的使用量。使用 `low` 用于更低成本的渲染，或 `high` 以更高分辨率渲染文件。默认为 `auto`. + 发送给模型的文件的细节级别。使用 `auto` 可让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 使用量。使用 `low` 以降低渲染成本，或 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -386,7 +386,7 @@ - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件的 ID。 - `file_url: optional string` @@ -394,11 +394,11 @@ - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送给模型的文件名。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会舍入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求中继承其 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -408,7 +408,7 @@ - `role: "unknown" or "user" or "assistant" or 5 more` - 消息的角色。以下之一： `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`，或 `tool`. + 消息的角色。可选值为 `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`，或 `tool`. - `"unknown"` @@ -428,7 +428,7 @@ - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 `incomplete`。当项目通过 API 返回时填充。 + 条目的状态。可选值为 `in_progress`, `completed`，或 `incomplete`。当通过 API 返回条目时填充。 - `"in_progress"` @@ -444,7 +444,7 @@ - `phase: optional "commentary" or "final_answer" or null` - 将 `assistant` 消息标记为中间评论（`commentary`）或最终答案（`final_answer`）。对于 `gpt-5.3-codex` 及更高版本的模型，在发送后续请求时，请在所有助手消息上保留并重新发送阶段——丢弃它可能会降低性能。不用于用户消息。 + 将 `assistant` 消息标记为中间推理过程（`commentary`）或最终答案（`final_answer`）。对于像 `gpt-5.3-codex` 及更高版本的模型，在发送后续请求时，请在所有助手消息上保留并重新发送 phase——删除它可能会降低性能。不用于用户消息。 - `"commentary"` @@ -470,8 +470,8 @@ - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。当项目通过 API 返回时填充。 + 条目的状态。可选值为 `in_progress`, `completed`，或 + `incomplete`。当通过 API 返回条目时填充。 - `"in_progress"` @@ -499,7 +499,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -507,7 +507,7 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `namespace: optional string` @@ -521,7 +521,7 @@ - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 你的代码生成的函数调用输出。 + 由你的代码生成的函数调用的输出。 可以是字符串或输出内容列表。 - `StringOutput = string` @@ -534,7 +534,7 @@ - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入到模型的文本。 + 发送给模型的文本输入。 - `ResponseInputImage object { detail, type, file_id, 2 more }` @@ -546,8 +546,8 @@ - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。当项目通过 API 返回时填充。 + 条目的状态。可选值为 `in_progress`, `completed`，或 + `incomplete`。当通过 API 返回条目时填充。 - `"in_progress"` @@ -573,7 +573,7 @@ - `type: "direct"` - 调用者类型。始终为 `direct`. + 调用方类型。始终为 `direct`. - `"direct"` @@ -581,21 +581,21 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` - 调用者类型。始终为 `program`. + 调用方类型。始终为 `program`. - `"program"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `name: optional string` - 产生输出的工具名称。 + 产生输出的工具的名称。 - `namespace: optional string` @@ -603,12 +603,12 @@ - `FileSearchCall object { id, queries, status, 2 more }` - 文件搜索工具调用的结果。参见 - [文件搜索指南](/docs/guides/tools-file-search) 以了解更多信息。 + 文件搜索 工具调用的结果。详见 + [文件搜索 指南](/docs/guides/tools-file-search) 了解更多信息。 - `id: string` - 文件搜索工具调用的唯一 ID。 + 文件搜索 工具调用的唯一 ID。 - `queries: array of string` @@ -616,7 +616,7 @@ - `status: "in_progress" or "searching" or "completed" or 2 more` - 文件搜索工具调用的状态。以下之一： `in_progress`, + 文件搜索 工具调用的状态。取值之一为 `in_progress`, `searching`, `incomplete` 或 `failed`, - `"in_progress"` @@ -631,7 +631,7 @@ - `type: "file_search_call"` - 文件搜索工具调用的类型。始终 `file_search_call`. + 文件搜索工具调用的类型。始终为 `file_search_call`. - `"file_search_call"` @@ -641,11 +641,11 @@ - `attributes: optional map[string or number or boolean] or null` - 可附加到对象上的16个键值对集合。这可用于 - 以结构化格式存储关于对象的额外信息，并 - 通过API或仪表盘查询对象。键是字符串 - ，最大长度为64个字符。值是字符串，最大 - 长度为512个字符、布尔值或数字。 + 可附加到对象的 16 组键值对。这可以用于 + 以结构化格式存储有关对象的附加信息， + 并通过API 或控制面板查询对象。键是字符串， + 最大长度为 64 个字符。值是字符串，最大 + 长度为 512 个字符、布尔值或数字。 - `string` @@ -655,7 +655,7 @@ - `file_id: optional string` - 文件的唯一ID。 + 文件的唯一 ID。 - `filename: optional string` @@ -663,7 +663,7 @@ - `score: optional number` - 文件的相关性得分——介于0和1之间的值。 + 文件的相关性分数——介于 0 和 1 之间的值。 - `text: optional string` @@ -671,31 +671,31 @@ - `WebSearchCall object { id, action, status, type }` - 网页搜索工具调用的结果。参见 - [网页搜索指南](/docs/guides/tools-web-search) 以了解更多信息。 + 网页搜索工具调用的结果。请参阅 + [网页搜索指南](/docs/guides/tools-web-search) 了解更多信息。 - `id: string` - 网页搜索工具调用的唯一ID。 + 网页搜索工具调用的唯一 ID。 - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - 描述此网页搜索调用中采取的具体操作的对象。 - 包含模型如何使用网络的详细信息（搜索、打开页面、在页面中查找）。 + 描述此次网页搜索调用中执行的具体操作的对象。 + 包含模型如何使用网络的详细信息（search、open_page、find_in_page）。 - `Search object { type, queries, query, sources }` - 动作类型“search”——执行网页搜索查询。 + 操作类型 "search"——执行网页搜索查询。 - `type: "search"` - 动作类型。 + 操作类型。 - `"search"` - `queries: optional array of string` - 搜索查询。 + 搜索查询列表。 - `query: optional string` @@ -717,11 +717,11 @@ - `OpenPage object { type, url }` - 操作类型“open_page”——打开搜索结果中的特定 URL。 + 操作类型 "open_page" - 打开搜索结果中的某个特定 URL。 - `type: "open_page"` - 动作类型。 + 操作类型。 - `"open_page"` @@ -731,21 +731,21 @@ - `FindInPage object { pattern, type, url }` - 操作类型“find_in_page”：在已加载的页面中搜索模式。 + 操作类型 "find_in_page"：在已加载的页面中搜索某个模式。 - `pattern: string` - 要在页面中搜索的模式或文本。 + 在页面中搜索的模式或文本。 - `type: "find_in_page"` - 动作类型。 + 操作类型。 - `"find_in_page"` - `url: string` - 搜索模式的页面 URL。 + 在其中搜索模式的页面的 URL。 - `status: "in_progress" or "searching" or "completed" or "failed"` @@ -775,7 +775,7 @@ - `result: string or null` - 以 base64 编码的生成的图像。 + 以 base64 编码的生成图像。 - `status: "in_progress" or "completed" or "generating" or "failed"` @@ -798,7 +798,7 @@ - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` 对计算机使用工具的工具调用。请参阅 - [计算机使用指南](/docs/guides/tools-computer-use) 以了解更多信息。 + [computer use guide](/docs/guides/tools-computer-use) 了解更多信息。 - `id: string` @@ -806,11 +806,11 @@ - `call_id: string` - 用于响应工具调用并返回输出的标识符。 + 使用输出响应该工具调用时所使用的标识符。 - `pending_safety_checks: array of object { id, code, message }` - 计算机调用待处理的安全检查。 + 计算机调用的待处理安全检查。 - `id: string` @@ -822,12 +822,12 @@ - `message: optional string or null` - 有关待处理安全检查的详细信息。 + 关于待处理安全检查的详细信息。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。当项目通过 API 返回时填充。 + 条目的状态。可选值为 `in_progress`, `completed`，或 + `incomplete`。当通过 API 返回条目时填充。 - `"in_progress"` @@ -837,21 +837,21 @@ - `type: "computer_call"` - 计算机调用的类型。始终 `computer_call`. + 计算机调用的类型。始终为 `computer_call`. - `"computer_call"` - `action: optional ComputerAction` - 单击操作。 + 一次点击操作。 - `Click object { button, type, x, 2 more }` - 单击操作。 + 一次点击操作。 - `button: "left" or "right" or "wheel" or 2 more` - 指示单击期间按下了哪个鼠标按钮。之一 `left`, `right`, `wheel`, `back`，或 `forward`. + 指示点击时按下了哪个鼠标按钮。其值为以下之一 `left`, `right`, `wheel`, `back`，或 `forward`. - `"left"` @@ -865,25 +865,25 @@ - `type: "click"` - 指定事件类型。对于单击操作，此属性始终为 `click`. + 指定事件类型。对于点击操作，该属性始终为 `click`. - `"click"` - `x: number` - 发生单击的 x 坐标。 + 点击发生位置的 x 坐标。 - `y: number` - 发生单击的 y 坐标。 + 点击发生位置的 y 坐标。 - `keys: optional array of string or null` - 单击时按住的按键。 + 点击时按住的按键。 - `DoubleClick object { keys, type, x, y }` - 双击操作。 + 一次双击操作。 - `keys: array of string or null` @@ -891,25 +891,25 @@ - `type: "double_click"` - 指定事件类型。对于双击操作，此属性始终设置为 `double_click`. + 指定事件类型。对于双击操作，该属性始终设置为 `double_click`. - `"double_click"` - `x: number` - 发生双击的 x 坐标。 + 双击发生位置的 x 坐标。 - `y: number` - 发生双击的 y 坐标。 + 双击发生位置的 y 坐标。 - `Drag object { path, type, keys }` - 拖拽操作。 + 一次拖拽操作。 - `path: array of object { x, y }` - 表示拖拽操作路径的坐标数组。坐标将以对象数组的形式出现，例如 + 表示拖拽操作路径的坐标数组。坐标以对象数组的形式出现，例如 ``` [ @@ -928,21 +928,21 @@ - `type: "drag"` - 指定事件类型。对于拖拽操作，此属性始终设置为 `drag`. + 指定事件类型。对于拖拽操作，该属性始终设置为 `drag`. - `"drag"` - `keys: optional array of string or null` - 拖拽鼠标时按住的按键。 + 拖动鼠标时按住的按键。 - `Keypress object { keys, type }` - 模型想要执行的一系列按键操作。 + 模型希望执行的按键操作的集合。 - `keys: array of string` - 模型请求按下的按键组合。这是一个字符串数组，每个字符串表示一个按键。 + 模型请求按下的按键组合。这是一组字符串，每个字符串表示一个按键。 - `type: "keypress"` @@ -974,11 +974,11 @@ - `Screenshot object { type }` - 截屏操作。 + 截图操作。 - `type: "screenshot"` - 指定事件类型。对于截屏操作，此属性始终设置为 `screenshot`. + 指定事件类型。对于截图操作，此属性始终设置为 `screenshot`. - `"screenshot"` @@ -1014,7 +1014,7 @@ - `Type object { text, type }` - 输入文本的操作。 + 用于输入文本的操作。 - `text: string` @@ -1028,7 +1028,7 @@ - `Wait object { type }` - 等待操作。 + 一个等待操作。 - `type: "wait"` @@ -1038,24 +1038,24 @@ - `actions: optional ComputerActionList` - 展平的批量操作，适用于 `computer_use`。每个操作都包含一个 - `type` 判别器和操作特定字段。 + 展平后的批量操作 `computer_use`。每个操作包含一个 + `type` 判别字段以及操作特有的字段。 - `Click object { button, type, x, 2 more }` - 单击操作。 + 一次点击操作。 - `DoubleClick object { keys, type, x, y }` - 双击操作。 + 一次双击操作。 - `Drag object { path, type, keys }` - 拖拽操作。 + 一次拖拽操作。 - `Keypress object { keys, type }` - 模型想要执行的一系列按键操作。 + 模型希望执行的按键操作的集合。 - `Move object { type, x, y, keys }` @@ -1063,7 +1063,7 @@ - `Screenshot object { type }` - 截屏操作。 + 截图操作。 - `Scroll object { scroll_x, scroll_y, type, 3 more }` @@ -1071,11 +1071,11 @@ - `Type object { text, type }` - 输入文本的操作。 + 用于输入文本的操作。 - `Wait object { type }` - 等待操作。 + 一个等待操作。 - `ComputerCallOutput object { id, call_id, output, 4 more }` @@ -1085,11 +1085,11 @@ - `call_id: string` - 产生该输出的计算机工具调用的 ID。 + 生成该输出的计算机工具调用的 ID。 - `output: ResponseComputerToolCallOutputScreenshot` - 与计算机使用工具一起使用的计算机截图图像。 + 与计算机使用工具配合使用的计算机截图图像。 - `type: "computer_screenshot"` @@ -1100,16 +1100,16 @@ - `file_id: optional string` - 包含截图的上传文件的标识符。 + 包含屏幕截图的上传文件的标识符。 - `image_url: optional string` - 截图图像的 URL。 + 屏幕截图图像的 URL。 - `status: "completed" or "incomplete" or "failed" or "in_progress"` - 消息输入的状态。可选值之一为 `in_progress`, `completed`，或 - `incomplete`。当通过 API 返回输入项时会填充此字段。 + 消息输入的状态。取值为 `in_progress`, `completed`，或 + `incomplete`。之一。当输入项通过 API 返回时填充。 - `"completed"` @@ -1127,7 +1127,7 @@ - `acknowledged_safety_checks: optional array of object { id, code, message }` - 由 API 报告、且已被 + 由 API 报告的、已被 开发者确认的安全检查。 - `id: string` @@ -1140,11 +1140,11 @@ - `message: optional string or null` - 有关待处理安全检查的详细信息。 + 关于待处理安全检查的详细信息。 - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `ToolSearchCall object { id, arguments, call_id, 4 more }` @@ -1158,7 +1158,7 @@ - `call_id: string or null` - 由模型生成的工具搜索调用的唯一 ID。 + 模型生成的工具搜索调用的唯一 ID。 - `execution: "server" or "client"` @@ -1170,7 +1170,7 @@ - `status: "in_progress" or "completed" or "incomplete"` - 所记录的调出（tool search）调用条目的状态。 + 已记录的工具搜索调用项的状态。 - `"in_progress"` @@ -1180,23 +1180,23 @@ - `type: "tool_search_call"` - 条目的类型。始终为 `tool_search_call`. + 该项的类型。始终为 `tool_search_call`. - `"tool_search_call"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `ToolSearchOutput object { id, call_id, execution, 4 more }` - `id: string` - 调出（tool search）输出条目的唯一 ID。 + 工具搜索输出项的唯一 ID。 - `call_id: string or null` - 由模型生成的工具搜索调用的唯一 ID。 + 模型生成的工具搜索调用的唯一 ID。 - `execution: "server" or "client"` @@ -1208,7 +1208,7 @@ - `status: "in_progress" or "completed" or "incomplete"` - 所记录的调出（tool search）输出条目的状态。 + 已记录的工具搜索输出项的状态。 - `"in_progress"` @@ -1218,23 +1218,23 @@ - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - 由调出（tool search）返回的已加载工具定义。 + 工具搜索返回的已加载工具定义。 - `Function object { name, parameters, strict, 5 more }` - 在你自己的代码中定义模型可以选择调用的函数。了解更多 [函数调用](https://platform.openai.com/docs/guides/function-calling). + 在你自己代码中定义一个可供模型选择调用的函数。了解更多关于 [函数调用](https://platform.openai.com/docs/guides/function-calling). - `name: string` - 要调用的函数的名称。 + 要调用的函数名称。 - `parameters: map[unknown] or null` - 一个 JSON schema 对象，描述函数的参数。 + 描述该函数参数的 JSON schema 对象。 - `strict: boolean or null` - 是否对此函数工具强制实施严格参数验证。 + 是否对此函数工具强制执行严格的参数校验。 - `type: "function"` @@ -1252,19 +1252,19 @@ - `defer_loading: optional boolean` - 此函数是否延迟并通过调出（tool search）加载。 + 此函数是否被延迟加载并通过工具搜索加载。 - `description: optional string or null` - 函数的描述。模型据此决定是否调用该函数。 + 函数的描述。模型据此判断是否调用该函数。 - `output_schema: optional map[unknown] or null` - 一个 JSON schema 对象，描述此函数的字符串输出中编码的 JSON 值。 + 描述此函数字符串输出中所编码 JSON 值的 JSON schema 对象。 - `FileSearch object { type, vector_store_ids, filters, 2 more }` - 一种从上传文件中搜索相关内容的工具。了解更多关于 [文件搜索工具](https://platform.openai.com/docs/guides/tools-file-search). + 用于从已上传文件中搜索相关内容的工具。了解更多关于 [文件搜索 tool](https://platform.openai.com/docs/guides/tools-file-search). - `type: "file_search"` @@ -1274,19 +1274,19 @@ - `vector_store_ids: array of string` - 要搜索的向量存储的 ID。 + 要搜索的向量存储库的 ID。 - `filters: optional ComparisonFilter or CompoundFilter or null` - 要应用的过滤器。 + 要应用的筛选条件。 - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作，将指定的属性键与给定值进行比较的过滤器。 + 使用定义好的比较运算，将指定的属性键与给定值进行比较的筛选器。 - `key: string` - 要与值进行比较的键。 + 要与该值进行比较的键。 - `type: "eq" or "ne" or "gt" or 5 more` @@ -1298,8 +1298,8 @@ - `gte`: 大于或等于 - `lt`: 小于 - `lte`: 小于或等于 - - `in`: 属于 - - `nin`: 不属于 + - `in`: 包含于 + - `nin`: 不包含于 - `"eq"` @@ -1335,21 +1335,21 @@ - `CompoundFilter object { filters, type }` - 使用以下方式组合多个过滤器 `and` 或 `or`. + 使用以下方式组合多个筛选器 `and` 或 `or`. - `filters: array of ComparisonFilter or unknown` - 要组合的过滤器数组。项目可以是 `ComparisonFilter` 或 `CompoundFilter`. + 要组合的筛选器数组。各项可以是 `ComparisonFilter` 或 `CompoundFilter`. - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作，将指定的属性键与给定值进行比较的过滤器。 + 使用定义好的比较运算，将指定的属性键与给定值进行比较的筛选器。 - `unknown` - `type: "and" or "or"` - 操作类型： `and` 或 `or`. + 运算类型： `and` 或 `or`. - `"and"` @@ -1357,7 +1357,7 @@ - `max_num_results: optional number` - 要返回的最大结果数量。该数字应在1到50之间（含1和50）。 + 要返回的最大结果数。该数值应介于 1 到 50（含）之间。 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` @@ -1365,15 +1365,15 @@ - `hybrid_search: optional object { embedding_weight, text_weight }` - 启用混合搜索时，控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡的权重。 + 启用混合搜索时，用于控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡方式的权重。 - `embedding_weight: number` - 嵌入在倒数排名融合中的权重。 + 倒数排名融合中嵌入的权重。 - `text_weight: number` - 文本在倒数排名融合中的权重。 + 倒数排名融合中文本的权重。 - `ranker: optional "auto" or "default-2024-11-15"` @@ -1385,33 +1385,33 @@ - `score_threshold: optional number` - 文件搜索的分数阈值，为0到1之间的数字。接近1的数字将尝试仅返回最相关的结果，但可能返回较少的结果。 + 文件搜索的分数阈值，取值范围为 0 到 1 之间。越接近 1 的数值越会尝试只返回相关性最高的结果，但返回的结果数量可能会更少。 - `Computer object { type }` - 一个控制虚拟计算机的工具。了解更多关于 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: "computer"` - 计算机工具的类型。始终为 `computer`. + computer tool 的类型。始终为 `computer`. - `"computer"` - `ComputerUsePreview object { display_height, display_width, environment, type }` - 一个控制虚拟计算机的工具。了解更多关于 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: number` - 计算机显示器的高度。 + 计算机显示屏的高度。 - `display_width: number` - 计算机显示器的宽度。 + 计算机显示屏的宽度。 - `environment: "windows" or "mac" or "linux" or 2 more` - 要控制的计算机环境的类型。 + 要控制的计算机环境类型。 - `"windows"` @@ -1425,18 +1425,18 @@ - `type: "computer_use_preview"` - 计算机使用工具的类型。始终为 `computer_use_preview`. + computer use 工具的类型。始终为 `computer_use_preview`. - `"computer_use_preview"` - `WebSearch object { type, external_web_access, filters, 2 more }` - 搜索互联网以查找与提示相关的来源。了解更多关于 - [网页搜索工具](/docs/guides/tools-web-search). + 在互联网上搜索与提示相关的信息源。详细了解 + [网页搜索 工具](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` - 网页搜索工具的类型。其中之一为 `web_search` 或 `web_search_2025_08_26`. + 网页搜索 工具的类型。可选值为 `web_search` 或 `web_search_2025_08_26`. - `"web_search"` @@ -1444,22 +1444,22 @@ - `external_web_access: optional boolean` - 允许网页搜索实时访问互联网。省略时默认为true。当为false时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 + 允许 网页搜索 进行实时互联网访问。若省略，默认值为 true。当设置为 false 时，网页搜索 工具将以离线/仅缓存模式运行，且不会获取新的外部内容。 - `filters: optional object { allowed_domains } or null` - 搜索的过滤器。 + 搜索的过滤条件。 - `allowed_domains: optional array of string or null` - 搜索允许的域名。如果未提供，则允许所有域名。 - 提供的域名的子域名也允许。 + 搜索所允许的域名。如果未提供，则允许所有域名。 + 同时也允许所提供域名的子域名。 示例： `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。其中之一为 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间使用量的高级指引。可选值为 `low`, `medium`，或 `high`. `medium` 为默认值。 - `"low"` @@ -1473,15 +1473,15 @@ - `city: optional string or null` - 用户的城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两个字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户的地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` @@ -1489,14 +1489,14 @@ - `type: optional "approximate"` - 位置近似的类型。始终为 `approximate`. + 位置近似值的类型。始终为 `approximate`. - `"approximate"` - `Mcp object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议为模型提供额外工具的访问权限 - (MCP) 服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol + (MCP) 服务器为模型提供对其他工具的访问能力。 [详细了解 MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1518,20 +1518,20 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称的字符串数组 + 允许使用的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1540,26 +1540,26 @@ - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌， - 可与自定义 MCP 服务器 URL 或服务连接器配合使用。你的应用程序 - 必须处理 OAuth 授权流程，并在此处提供令牌。 + 可用于远程 MCP 服务器的 OAuth 访问令牌,使用自定义 MCP + 服务器 URL 或服务连接器均可。你的应用必须 + 处理 OAuth 授权流程,并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，例如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符,例如 ChatGPT 中可用的连接器。以下值之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器 [的信息](/docs/guides/tools-remote-mcp#connectors). - 当前支持的 `connector_id` 值为： + 当前支持的值 `connector_id` 包括: - - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google Calendar： `connector_googlecalendar` - - Google Drive： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook Calendar： `connector_outlookcalendar` - - Outlook Email： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -1579,11 +1579,11 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否推迟发现并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载,并通过工具搜索发现。 - `headers: optional map[string] or null` - 发送到 MCP 服务器的可选 HTTP 头。用于身份验证 + 发送到 MCP 服务器的可选 HTTP 标头,用于身份验证 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` @@ -1593,17 +1593,17 @@ - `McpToolApprovalFilter object { always, never }` 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的筛选器对象 - 。 + `always`, `never`,或与工具关联的过滤器对象 + 需要审批的工具。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1612,12 +1612,12 @@ - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1626,9 +1626,9 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一的审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。之一。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -1636,27 +1636,27 @@ - `server_description: optional string` - MCP 服务器的可选描述，用于提供更多上下文。 + MCP 服务器的可选描述,用于提供更多上下文。 - `server_url: optional string` - MCP 服务器的 URL。必须提供 `server_url`, `connector_id`，或 - `tunnel_id` 之一。 + MCP 服务器的 URL。必须提供以下之一 `server_url`, `connector_id`，或 + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而非直接的服务器 URL。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。 + 用于代替直接服务器 URL 的 Secure MCP Tunnel ID。必须提供以下之一 + `server_url`, `connector_id`，或 `tunnel_id` 。 - `CodeInterpreter object { container, type, allowed_callers }` - 一种运行 Python 代码以帮助生成提示响应的工具。 + 用于运行 Python 代码以帮助生成提示响应的工具。 - `container: string or object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器。可以是容器 ID 或指定 - 上传文件 ID 以在代码中可用的对象，以及 - 可选的 `memory_limit` 设置。 + 代码解释器容器。可以是容器 ID,或者是用于指定 + 可在代码中使用的已上传文件 ID,以及可选的 + 可选的 `memory_limit` 设置的对象。 - `string` @@ -1664,7 +1664,7 @@ - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器的配置。可选择指定要在其上运行代码的文件的 ID。 + 代码解释器容器的配置。可选择指定要对其运行代码的文件 ID。 - `type: "auto"` @@ -1674,7 +1674,7 @@ - `file_ids: optional array of string` - 可选的上传文件列表，用于让你的代码可用。 + 要提供给代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -1704,33 +1704,33 @@ - `allowed_domains: array of string` - 当类型为时，允许的域名列表 `allowlist`. + 当类型为时的允许域名列表 `allowlist`. - `type: "allowlist"` - 仅允许对指定域名的出站网络访问。始终 `allowlist`. + 仅允许向指定域发出出站网络访问。始终 `allowlist`. - `"allowlist"` - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - 用于白名单域名的可选域范围密钥。 + 用于白名单域的可选域作用域密钥。 - `domain: string` - 与密钥关联的域名。 + 与密钥关联的域。 - `name: string` - 要为该域名注入的密钥名称。 + 为该域名注入的密钥的名称。 - `value: string` - 要为该域名注入的密钥值。 + 为该域名注入的密钥值。 - `type: "code_interpreter"` - 代码解释器工具的类型。始终 `code_interpreter`. + 代码解释器工具的类型。始终为 `code_interpreter`. - `"code_interpreter"` @@ -1746,23 +1746,23 @@ - `type: "programmatic_tool_calling"` - 工具的类型。始终 `programmatic_tool_calling`. + 工具的类型。始终为 `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `ImageGeneration object { type, action, background, 9 more }` - 一种使用 GPT 图像模型生成图像的工具。 + 使用 GPT 图像模型生成图像的工具。 - `type: "image_generation"` - 图像生成工具的类型。始终 `image_generation`. + 图像生成工具的类型。始终为 `image_generation`. - `"image_generation"` - `action: optional "generate" or "edit" or "auto"` - 是生成新图像还是编辑现有图像。默认值： `auto`. + 是生成新图像还是编辑现有图像。默认值为： `auto`. - `"generate"` @@ -1772,11 +1772,11 @@ - `background: optional "transparent" or "opaque" or "auto"` - 设置生成图像的背景。选项之一为 `transparent`, - `opaque`，或 `auto`。透明背景可用于 - 支持的 GPT 图像模型。对于 `gpt-image-2` 以及 - `gpt-image-2-2026-04-21`，此支持处于预览阶段。使用 - `transparent`，时，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. + 设置生成图像的背景。可选值为 `transparent`, + `opaque`，或 `auto`。透明背景适用于 + 支持的 GPT Image 模型。对于 `gpt-image-2` 且 + `gpt-image-2-2026-04-21`，该支持处于预览阶段。使用时 + `transparent`，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. - `"transparent"` @@ -1786,7 +1786,7 @@ - `input_fidelity: optional "high" or "low" or null` - 控制模型在匹配输入图像的风格和特征（尤其是面部特征）时投入的努力程度。此参数仅支持 `gpt-image-1` 以及 `gpt-image-1.5` 及更高版本模型，不支持 `gpt-image-1-mini`。支持 `high` 以及 `low`。默认值为 `low`. + 控制模型在匹配输入图像风格和特征（尤其是面部特征）时所投入的精力。此参数仅在 `gpt-image-1` 且 `gpt-image-1.5` 及更高版本的模型中受支持，在 `gpt-image-1-mini`。中不受支持。支持 `high` 且 `low`。之一。默认为 `low`. - `"high"` @@ -1794,7 +1794,7 @@ - `input_image_mask: optional object { file_id, image_url }` - 用于修复的可选遮罩。包含 `image_url` + 用于局部重绘的可选遮罩。包含 `image_url` （字符串，可选）和 `file_id` （字符串，可选）。 - `file_id: optional string` @@ -1807,7 +1807,7 @@ - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。可选项为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -1816,7 +1816,7 @@ - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。可选项为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -1833,7 +1833,7 @@ - `moderation: optional "auto" or "low"` - 生成图像的审核级别。默认值： `auto`. + 生成图像的内容审核级别。默认值： `auto`. - `"auto"` @@ -1845,7 +1845,7 @@ - `output_format: optional "png" or "webp" or "jpeg"` - 生成图像的输出格式。可选项为 `png`, `webp`，或 + 生成图像的输出格式。可选值为 `png`, `webp`，或 `jpeg`。默认值： `png`. - `"png"` @@ -1856,11 +1856,11 @@ - `partial_images: optional number` - 流式模式下生成的局部图像数量，取值范围从 0（默认值）到 3。 + 流式模式下要生成的中间图像数量，范围为 0（默认值）到 3。 - `quality: optional "low" or "medium" or "high" or "auto"` - 生成图像的质量。可选项为 `low`, `medium`, `high`, + 生成图像的质量。可选值为 `low`, `medium`, `high`, 或 `auto`。默认值： `auto`. - `"low"` @@ -1873,13 +1873,13 @@ - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 以及 `gpt-image-2-2026-04-21`，支持任意分辨率，如 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽和高都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。分辨率高于 `2560x1440` 为实验性质，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`,以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`,使用以下之一 `256x256`, `512x512`，或 `1024x1024`. 对于 `dall-e-3`,使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持任意分辨率，格式为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须同时能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持，适用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下之一： `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，请使用以下之一： `1024x1024`, `1792x1024`，或 `1024x1792`. - `string` - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 以及 `gpt-image-2-2026-04-21`，支持任意分辨率，如 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽和高都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。分辨率高于 `2560x1440` 为实验性质，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`,以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`,使用以下之一 `256x256`, `512x512`，或 `1024x1024`. 对于 `dall-e-3`,使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持任意分辨率，格式为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须同时能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持，适用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下之一： `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，请使用以下之一： `1024x1024`, `1792x1024`，或 `1024x1792`. - `"1024x1024"` @@ -1891,7 +1891,7 @@ - `LocalShell object { type }` - 一种允许模型在本地环境中执行 shell 命令的工具。 + 允许模型在本地环境中执行 shell 命令的工具。 - `type: "local_shell"` @@ -1901,7 +1901,7 @@ - `Shell object { type, allowed_callers, environment }` - 一种允许模型执行 shell 命令的工具。 + 允许模型执行 shell 命令的工具。 - `type: "shell"` @@ -1923,13 +1923,13 @@ - `type: "container_auto"` - 自动为此请求创建容器 + 自动为此请求创建一个容器 - `"container_auto"` - `file_ids: optional array of string` - 可选的上传文件列表，用于让你的代码可用。 + 要提供给代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -1953,7 +1953,7 @@ - `skills: optional array of SkillReference or InlineSkill` - 可选的技能列表，按 id 或内联数据引用。 + 通过 id 或内联数据引用的可选技能列表。 - `SkillReference object { skill_id, type, version }` @@ -1963,13 +1963,13 @@ - `type: "skill_reference"` - 引用使用 /v1/skills 端点创建的技能。 + 引用通过 /v1/skills 端点创建的技能。 - `"skill_reference"` - `version: optional string` - 可选的技能版本。使用正整数或‘latest’。省略则使用默认值。 + 可选的技能版本。使用正整数或 'latest'。省略时使用默认值。 - `InlineSkill object { description, name, source, type }` @@ -1983,7 +1983,7 @@ - `source: InlineSkillSource` - 内联技能负载 + 内联技能载荷 - `data: string` @@ -1991,19 +1991,19 @@ - `media_type: "application/zip"` - 内联技能负载的媒体类型。必须是 `application/zip`. + 内联技能载荷的媒体类型。必须为 `application/zip`. - `"application/zip"` - `type: "base64"` - 内联技能来源的类型。必须是 `base64`. + 内联技能源的类型。必须为 `base64`. - `"base64"` - `type: "inline"` - 为此请求定义一个内联技能。 + 为本次请求定义一个内联技能。 - `"inline"` @@ -2011,7 +2011,7 @@ - `type: "local"` - 使用本地计算机环境。 + 使用本地计算环境。 - `"local"` @@ -2029,13 +2029,13 @@ - `path: string` - 包含技能的目录路径。 + 包含该技能的目录路径。 - `ContainerReference object { container_id, type }` - `container_id: string` - 被引用容器的 ID。 + 所引用容器的 ID。 - `type: "container_reference"` @@ -2045,7 +2045,7 @@ - `Custom object { name, type, allowed_callers, 3 more }` - 一种自定义工具，使用指定格式处理输入。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解有关 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2067,7 +2067,7 @@ - `defer_loading: optional boolean` - 此工具是否应延迟并通过工具搜索发现。 + 此工具是否应被延后并通过工具搜索发现。 - `description: optional string` @@ -2079,7 +2079,7 @@ - `Text object { type }` - 无约束的自由文本。 + 无约束的自由格式文本。 - `type: "text"` @@ -2097,7 +2097,7 @@ - `syntax: "lark" or "regex"` - 语法定义的语法。其中之一是 `lark` 或 `regex`. + 语法定义的语法。其取值之一为 `lark` 或 `regex`. - `"lark"` @@ -2105,25 +2105,25 @@ - `type: "grammar"` - 语法格式。始终 `grammar`. + 语法格式。始终为 `grammar`. - `"grammar"` - `Namespace object { description, name, tools, type }` - 将函数/自定义工具分组到共享命名空间中。 + 在共享命名空间下对 function/自定义工具进行分组。 - `description: string` - 向模型显示的命名空间描述。 + 展示给模型的命名空间描述。 - `name: string` - 工具调用中使用的命名空间名称（例如， `crm`). + 在工具调用中使用的命名空间名称（例如， `crm`). - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - 此命名空间内可用的函数/自定义工具。 + 此命名空间内可用的 function/自定义工具。 - `Function object { name, type, allowed_callers, 5 more }` @@ -2143,23 +2143,23 @@ - `defer_loading: optional boolean` - 此函数是否应延迟并通过工具搜索发现。 + 此 function 是否应被延迟并通过工具搜索发现。 - `description: optional string or null` - `output_schema: optional map[unknown] or null` - 描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema。这不描述内容数组输出。 + 用于描述该 function 工具的字符串输出中所编码 JSON 值的 JSON Schema。此 Schema 不描述 content 数组形式的输出。 - `parameters: optional unknown or null` - `strict: optional boolean or null` - 是否强制执行严格的参数验证。如果省略，Responses 会在 schema 兼容时尝试使用严格验证，否则回退到非严格验证。 + 是否强制执行严格的参数校验。如果省略，响应接口 会在 schema 兼容时尝试使用严格校验，否则回退到非严格校验。 - `Custom object { name, type, allowed_callers, 3 more }` - 一种自定义工具，使用指定格式处理输入。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解有关 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2181,7 +2181,7 @@ - `defer_loading: optional boolean` - 此工具是否应延迟并通过工具搜索发现。 + 此工具是否应被延后并通过工具搜索发现。 - `description: optional string` @@ -2193,27 +2193,27 @@ - `type: "namespace"` - 工具的类型。始终 `namespace`. + 工具的类型。始终为 `namespace`. - `"namespace"` - `ToolSearch object { type, description, execution, parameters }` - 用于延迟工具的托管或 BYOT 工具搜索配置。 + 用于延迟工具的托管式或 BYOT 工具搜索配置。 - `type: "tool_search"` - 工具的类型。始终 `tool_search`. + 工具的类型。始终为 `tool_search`. - `"tool_search"` - `description: optional string or null` - 向模型显示的用于客户端执行的工具搜索工具的描述。 + 展示给模型的客户端执行的工具搜索工具描述。 - `execution: optional "server" or "client"` - 工具搜索是由服务器还是客户端执行。 + 工具搜索是由服务端执行还是由客户端执行。 - `"server"` @@ -2221,15 +2221,15 @@ - `parameters: optional unknown or null` - 用于客户端执行的工具搜索工具的参数 schema。 + 客户端执行的工具搜索工具的参数 schema。 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - 此工具搜索网络以获取相关结果用于响应中。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). + 此工具会在网络上搜索相关内容以用于回复。详细了解 [网页搜索 工具](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 网页搜索工具的类型。其中之一为 `web_search_preview` 或 `web_search_preview_2025_03_11`. + 网页搜索 工具的类型。可选值为 `web_search_preview` 或 `web_search_preview_2025_03_11`. - `"web_search_preview"` @@ -2243,7 +2243,7 @@ - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。其中之一为 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间使用量的高级指引。可选值为 `low`, `medium`，或 `high`. `medium` 为默认值。 - `"low"` @@ -2253,25 +2253,25 @@ - `user_location: optional object { type, city, country, 2 more } or null` - 用户的位置。 + 用户的位置信息。 - `type: "approximate"` - 位置近似的类型。始终为 `approximate`. + 位置近似值的类型。始终为 `approximate`. - `"approximate"` - `city: optional string or null` - 用户的城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两个字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户的地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` @@ -2279,11 +2279,11 @@ - `ApplyPatch object { type, allowed_callers }` - 允许助手使用统一差异创建、删除或更新文件。 + 允许助手使用 unified diff 创建、删除或更新文件。 - `type: "apply_patch"` - 工具的类型。始终 `apply_patch`. + 工具的类型。始终为 `apply_patch`. - `"apply_patch"` @@ -2297,23 +2297,23 @@ - `type: "tool_search_output"` - 条目的类型。始终为 `tool_search_output`. + 该项的类型。始终为 `tool_search_output`. - `"tool_search_output"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `AdditionalTools object { id, role, tools, type }` - `id: string` - 其他工具项的唯一 ID。 + 该 additional tools 项的唯一 ID。 - `role: "unknown" or "user" or "assistant" or 5 more` - 提供其他工具的角色。 + 提供这些 additional tools 的角色。 - `"unknown"` @@ -2333,23 +2333,23 @@ - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - 在此项中可用的额外工具定义。 + 在此条目中提供的额外工具定义。 - `Function object { name, parameters, strict, 5 more }` - 在你自己的代码中定义模型可以选择调用的函数。了解更多 [函数调用](https://platform.openai.com/docs/guides/function-calling). + 在你自己代码中定义一个可供模型选择调用的函数。了解更多关于 [函数调用](https://platform.openai.com/docs/guides/function-calling). - `name: string` - 要调用的函数的名称。 + 要调用的函数名称。 - `parameters: map[unknown] or null` - 一个 JSON schema 对象，描述函数的参数。 + 描述该函数参数的 JSON schema 对象。 - `strict: boolean or null` - 是否对此函数工具强制实施严格参数验证。 + 是否对此函数工具强制执行严格的参数校验。 - `type: "function"` @@ -2367,19 +2367,19 @@ - `defer_loading: optional boolean` - 此函数是否延迟并通过调出（tool search）加载。 + 此函数是否被延迟加载并通过工具搜索加载。 - `description: optional string or null` - 函数的描述。模型据此决定是否调用该函数。 + 函数的描述。模型据此判断是否调用该函数。 - `output_schema: optional map[unknown] or null` - 一个 JSON schema 对象，描述此函数的字符串输出中编码的 JSON 值。 + 描述此函数字符串输出中所编码 JSON 值的 JSON schema 对象。 - `FileSearch object { type, vector_store_ids, filters, 2 more }` - 一种从上传文件中搜索相关内容的工具。了解更多关于 [文件搜索工具](https://platform.openai.com/docs/guides/tools-file-search). + 用于从已上传文件中搜索相关内容的工具。了解更多关于 [文件搜索 tool](https://platform.openai.com/docs/guides/tools-file-search). - `type: "file_search"` @@ -2389,23 +2389,23 @@ - `vector_store_ids: array of string` - 要搜索的向量存储的 ID。 + 要搜索的向量存储库的 ID。 - `filters: optional ComparisonFilter or CompoundFilter or null` - 要应用的过滤器。 + 要应用的筛选条件。 - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作，将指定的属性键与给定值进行比较的过滤器。 + 使用定义好的比较运算，将指定的属性键与给定值进行比较的筛选器。 - `CompoundFilter object { filters, type }` - 使用以下方式组合多个过滤器 `and` 或 `or`. + 使用以下方式组合多个筛选器 `and` 或 `or`. - `max_num_results: optional number` - 要返回的最大结果数量。该数字应在1到50之间（含1和50）。 + 要返回的最大结果数。该数值应介于 1 到 50（含）之间。 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` @@ -2413,15 +2413,15 @@ - `hybrid_search: optional object { embedding_weight, text_weight }` - 启用混合搜索时，控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡的权重。 + 启用混合搜索时，用于控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡方式的权重。 - `embedding_weight: number` - 嵌入在倒数排名融合中的权重。 + 倒数排名融合中嵌入的权重。 - `text_weight: number` - 文本在倒数排名融合中的权重。 + 倒数排名融合中文本的权重。 - `ranker: optional "auto" or "default-2024-11-15"` @@ -2433,33 +2433,33 @@ - `score_threshold: optional number` - 文件搜索的分数阈值，为0到1之间的数字。接近1的数字将尝试仅返回最相关的结果，但可能返回较少的结果。 + 文件搜索的分数阈值，取值范围为 0 到 1 之间。越接近 1 的数值越会尝试只返回相关性最高的结果，但返回的结果数量可能会更少。 - `Computer object { type }` - 一个控制虚拟计算机的工具。了解更多关于 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: "computer"` - 计算机工具的类型。始终为 `computer`. + computer tool 的类型。始终为 `computer`. - `"computer"` - `ComputerUsePreview object { display_height, display_width, environment, type }` - 一个控制虚拟计算机的工具。了解更多关于 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: number` - 计算机显示器的高度。 + 计算机显示屏的高度。 - `display_width: number` - 计算机显示器的宽度。 + 计算机显示屏的宽度。 - `environment: "windows" or "mac" or "linux" or 2 more` - 要控制的计算机环境的类型。 + 要控制的计算机环境类型。 - `"windows"` @@ -2473,18 +2473,18 @@ - `type: "computer_use_preview"` - 计算机使用工具的类型。始终为 `computer_use_preview`. + computer use 工具的类型。始终为 `computer_use_preview`. - `"computer_use_preview"` - `WebSearch object { type, external_web_access, filters, 2 more }` - 搜索互联网以查找与提示相关的来源。了解更多关于 - [网页搜索工具](/docs/guides/tools-web-search). + 在互联网上搜索与提示相关的信息源。详细了解 + [网页搜索 工具](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` - 网页搜索工具的类型。其中之一为 `web_search` 或 `web_search_2025_08_26`. + 网页搜索 工具的类型。可选值为 `web_search` 或 `web_search_2025_08_26`. - `"web_search"` @@ -2492,22 +2492,22 @@ - `external_web_access: optional boolean` - 允许网页搜索实时访问互联网。省略时默认为true。当为false时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 + 允许 网页搜索 进行实时互联网访问。若省略，默认值为 true。当设置为 false 时，网页搜索 工具将以离线/仅缓存模式运行，且不会获取新的外部内容。 - `filters: optional object { allowed_domains } or null` - 搜索的过滤器。 + 搜索的过滤条件。 - `allowed_domains: optional array of string or null` - 搜索允许的域名。如果未提供，则允许所有域名。 - 提供的域名的子域名也允许。 + 搜索所允许的域名。如果未提供，则允许所有域名。 + 同时也允许所提供域名的子域名。 示例： `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。其中之一为 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间使用量的高级指引。可选值为 `low`, `medium`，或 `high`. `medium` 为默认值。 - `"low"` @@ -2521,15 +2521,15 @@ - `city: optional string or null` - 用户的城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两个字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户的地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` @@ -2537,14 +2537,14 @@ - `type: optional "approximate"` - 位置近似的类型。始终为 `approximate`. + 位置近似值的类型。始终为 `approximate`. - `"approximate"` - `Mcp object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议为模型提供额外工具的访问权限 - (MCP) 服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol + (MCP) 服务器为模型提供对其他工具的访问能力。 [详细了解 MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -2566,20 +2566,20 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称的字符串数组 + 允许使用的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2588,26 +2588,26 @@ - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌， - 可与自定义 MCP 服务器 URL 或服务连接器配合使用。你的应用程序 - 必须处理 OAuth 授权流程，并在此处提供令牌。 + 可用于远程 MCP 服务器的 OAuth 访问令牌,使用自定义 MCP + 服务器 URL 或服务连接器均可。你的应用必须 + 处理 OAuth 授权流程,并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，例如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符,例如 ChatGPT 中可用的连接器。以下值之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器 [的信息](/docs/guides/tools-remote-mcp#connectors). - 当前支持的 `connector_id` 值为： + 当前支持的值 `connector_id` 包括: - - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google Calendar： `connector_googlecalendar` - - Google Drive： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook Calendar： `connector_outlookcalendar` - - Outlook Email： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -2627,11 +2627,11 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否推迟发现并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载,并通过工具搜索发现。 - `headers: optional map[string] or null` - 发送到 MCP 服务器的可选 HTTP 头。用于身份验证 + 发送到 MCP 服务器的可选 HTTP 标头,用于身份验证 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` @@ -2641,17 +2641,17 @@ - `McpToolApprovalFilter object { always, never }` 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的筛选器对象 - 。 + `always`, `never`,或与工具关联的过滤器对象 + 需要审批的工具。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2660,12 +2660,12 @@ - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是修改数据还是只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 表示某个工具是否会修改数据，或者是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), ，它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2674,9 +2674,9 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一的审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。之一。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -2684,27 +2684,27 @@ - `server_description: optional string` - MCP 服务器的可选描述，用于提供更多上下文。 + MCP 服务器的可选描述,用于提供更多上下文。 - `server_url: optional string` - MCP 服务器的 URL。必须提供 `server_url`, `connector_id`，或 - `tunnel_id` 之一。 + MCP 服务器的 URL。必须提供以下之一 `server_url`, `connector_id`，或 + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而非直接的服务器 URL。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。 + 用于代替直接服务器 URL 的 Secure MCP Tunnel ID。必须提供以下之一 + `server_url`, `connector_id`，或 `tunnel_id` 。 - `CodeInterpreter object { container, type, allowed_callers }` - 一种运行 Python 代码以帮助生成提示响应的工具。 + 用于运行 Python 代码以帮助生成提示响应的工具。 - `container: string or object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器。可以是容器 ID 或指定 - 上传文件 ID 以在代码中可用的对象，以及 - 可选的 `memory_limit` 设置。 + 代码解释器容器。可以是容器 ID,或者是用于指定 + 可在代码中使用的已上传文件 ID,以及可选的 + 可选的 `memory_limit` 设置的对象。 - `string` @@ -2712,7 +2712,7 @@ - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器的配置。可选择指定要在其上运行代码的文件的 ID。 + 代码解释器容器的配置。可选择指定要对其运行代码的文件 ID。 - `type: "auto"` @@ -2722,7 +2722,7 @@ - `file_ids: optional array of string` - 可选的上传文件列表，用于让你的代码可用。 + 要提供给代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -2746,7 +2746,7 @@ - `type: "code_interpreter"` - 代码解释器工具的类型。始终 `code_interpreter`. + 代码解释器工具的类型。始终为 `code_interpreter`. - `"code_interpreter"` @@ -2762,23 +2762,23 @@ - `type: "programmatic_tool_calling"` - 工具的类型。始终 `programmatic_tool_calling`. + 工具的类型。始终为 `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `ImageGeneration object { type, action, background, 9 more }` - 一种使用 GPT 图像模型生成图像的工具。 + 使用 GPT 图像模型生成图像的工具。 - `type: "image_generation"` - 图像生成工具的类型。始终 `image_generation`. + 图像生成工具的类型。始终为 `image_generation`. - `"image_generation"` - `action: optional "generate" or "edit" or "auto"` - 是生成新图像还是编辑现有图像。默认值： `auto`. + 是生成新图像还是编辑现有图像。默认值为： `auto`. - `"generate"` @@ -2788,11 +2788,11 @@ - `background: optional "transparent" or "opaque" or "auto"` - 设置生成图像的背景。选项之一为 `transparent`, - `opaque`，或 `auto`。透明背景可用于 - 支持的 GPT 图像模型。对于 `gpt-image-2` 以及 - `gpt-image-2-2026-04-21`，此支持处于预览阶段。使用 - `transparent`，时，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. + 设置生成图像的背景。可选值为 `transparent`, + `opaque`，或 `auto`。透明背景适用于 + 支持的 GPT Image 模型。对于 `gpt-image-2` 且 + `gpt-image-2-2026-04-21`，该支持处于预览阶段。使用时 + `transparent`，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. - `"transparent"` @@ -2802,7 +2802,7 @@ - `input_fidelity: optional "high" or "low" or null` - 控制模型在匹配输入图像的风格和特征（尤其是面部特征）时投入的努力程度。此参数仅支持 `gpt-image-1` 以及 `gpt-image-1.5` 及更高版本模型，不支持 `gpt-image-1-mini`。支持 `high` 以及 `low`。默认值为 `low`. + 控制模型在匹配输入图像风格和特征（尤其是面部特征）时所投入的精力。此参数仅在 `gpt-image-1` 且 `gpt-image-1.5` 及更高版本的模型中受支持，在 `gpt-image-1-mini`。中不受支持。支持 `high` 且 `low`。之一。默认为 `low`. - `"high"` @@ -2810,7 +2810,7 @@ - `input_image_mask: optional object { file_id, image_url }` - 用于修复的可选遮罩。包含 `image_url` + 用于局部重绘的可选遮罩。包含 `image_url` （字符串，可选）和 `file_id` （字符串，可选）。 - `file_id: optional string` @@ -2823,7 +2823,7 @@ - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。可选项为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -2832,7 +2832,7 @@ - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。可选项为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -2849,7 +2849,7 @@ - `moderation: optional "auto" or "low"` - 生成图像的审核级别。默认值： `auto`. + 生成图像的内容审核级别。默认值： `auto`. - `"auto"` @@ -2861,7 +2861,7 @@ - `output_format: optional "png" or "webp" or "jpeg"` - 生成图像的输出格式。可选项为 `png`, `webp`，或 + 生成图像的输出格式。可选值为 `png`, `webp`，或 `jpeg`。默认值： `png`. - `"png"` @@ -2872,11 +2872,11 @@ - `partial_images: optional number` - 流式模式下生成的局部图像数量，取值范围从 0（默认值）到 3。 + 流式模式下要生成的中间图像数量，范围为 0（默认值）到 3。 - `quality: optional "low" or "medium" or "high" or "auto"` - 生成图像的质量。可选项为 `low`, `medium`, `high`, + 生成图像的质量。可选值为 `low`, `medium`, `high`, 或 `auto`。默认值： `auto`. - `"low"` @@ -2889,13 +2889,13 @@ - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 以及 `gpt-image-2-2026-04-21`，支持任意分辨率，如 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽和高都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。分辨率高于 `2560x1440` 为实验性质，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`,以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`,使用以下之一 `256x256`, `512x512`，或 `1024x1024`. 对于 `dall-e-3`,使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持任意分辨率，格式为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须同时能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持，适用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下之一： `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，请使用以下之一： `1024x1024`, `1792x1024`，或 `1024x1792`. - `string` - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 以及 `gpt-image-2-2026-04-21`，支持任意分辨率，如 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽和高都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。分辨率高于 `2560x1440` 为实验性质，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`,以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`,使用以下之一 `256x256`, `512x512`，或 `1024x1024`. 对于 `dall-e-3`,使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持任意分辨率，格式为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须同时能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持，适用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下之一： `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，请使用以下之一： `1024x1024`, `1792x1024`，或 `1024x1792`. - `"1024x1024"` @@ -2907,7 +2907,7 @@ - `LocalShell object { type }` - 一种允许模型在本地环境中执行 shell 命令的工具。 + 允许模型在本地环境中执行 shell 命令的工具。 - `type: "local_shell"` @@ -2917,7 +2917,7 @@ - `Shell object { type, allowed_callers, environment }` - 一种允许模型执行 shell 命令的工具。 + 允许模型执行 shell 命令的工具。 - `type: "shell"` @@ -2943,7 +2943,7 @@ - `Custom object { name, type, allowed_callers, 3 more }` - 一种自定义工具，使用指定格式处理输入。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解有关 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2965,7 +2965,7 @@ - `defer_loading: optional boolean` - 此工具是否应延迟并通过工具搜索发现。 + 此工具是否应被延后并通过工具搜索发现。 - `description: optional string` @@ -2977,19 +2977,19 @@ - `Namespace object { description, name, tools, type }` - 将函数/自定义工具分组到共享命名空间中。 + 在共享命名空间下对 function/自定义工具进行分组。 - `description: string` - 向模型显示的命名空间描述。 + 展示给模型的命名空间描述。 - `name: string` - 工具调用中使用的命名空间名称（例如， `crm`). + 在工具调用中使用的命名空间名称（例如， `crm`). - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - 此命名空间内可用的函数/自定义工具。 + 此命名空间内可用的 function/自定义工具。 - `Function object { name, type, allowed_callers, 5 more }` @@ -3009,23 +3009,23 @@ - `defer_loading: optional boolean` - 此函数是否应延迟并通过工具搜索发现。 + 此 function 是否应被延迟并通过工具搜索发现。 - `description: optional string or null` - `output_schema: optional map[unknown] or null` - 描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema。这不描述内容数组输出。 + 用于描述该 function 工具的字符串输出中所编码 JSON 值的 JSON Schema。此 Schema 不描述 content 数组形式的输出。 - `parameters: optional unknown or null` - `strict: optional boolean or null` - 是否强制执行严格的参数验证。如果省略，Responses 会在 schema 兼容时尝试使用严格验证，否则回退到非严格验证。 + 是否强制执行严格的参数校验。如果省略，响应接口 会在 schema 兼容时尝试使用严格校验，否则回退到非严格校验。 - `Custom object { name, type, allowed_callers, 3 more }` - 一种自定义工具，使用指定格式处理输入。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解有关 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -3047,7 +3047,7 @@ - `defer_loading: optional boolean` - 此工具是否应延迟并通过工具搜索发现。 + 此工具是否应被延后并通过工具搜索发现。 - `description: optional string` @@ -3059,27 +3059,27 @@ - `type: "namespace"` - 工具的类型。始终 `namespace`. + 工具的类型。始终为 `namespace`. - `"namespace"` - `ToolSearch object { type, description, execution, parameters }` - 用于延迟工具的托管或 BYOT 工具搜索配置。 + 用于延迟工具的托管式或 BYOT 工具搜索配置。 - `type: "tool_search"` - 工具的类型。始终 `tool_search`. + 工具的类型。始终为 `tool_search`. - `"tool_search"` - `description: optional string or null` - 向模型显示的用于客户端执行的工具搜索工具的描述。 + 展示给模型的客户端执行的工具搜索工具描述。 - `execution: optional "server" or "client"` - 工具搜索是由服务器还是客户端执行。 + 工具搜索是由服务端执行还是由客户端执行。 - `"server"` @@ -3087,15 +3087,15 @@ - `parameters: optional unknown or null` - 用于客户端执行的工具搜索工具的参数 schema。 + 客户端执行的工具搜索工具的参数 schema。 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - 此工具搜索网络以获取相关结果用于响应中。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). + 此工具会在网络上搜索相关内容以用于回复。详细了解 [网页搜索 工具](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 网页搜索工具的类型。其中之一为 `web_search_preview` 或 `web_search_preview_2025_03_11`. + 网页搜索 工具的类型。可选值为 `web_search_preview` 或 `web_search_preview_2025_03_11`. - `"web_search_preview"` @@ -3109,7 +3109,7 @@ - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。其中之一为 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间使用量的高级指引。可选值为 `low`, `medium`，或 `high`. `medium` 为默认值。 - `"low"` @@ -3119,25 +3119,25 @@ - `user_location: optional object { type, city, country, 2 more } or null` - 用户的位置。 + 用户的位置信息。 - `type: "approximate"` - 位置近似的类型。始终为 `approximate`. + 位置近似值的类型。始终为 `approximate`. - `"approximate"` - `city: optional string or null` - 用户的城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两个字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户的地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` @@ -3145,11 +3145,11 @@ - `ApplyPatch object { type, allowed_callers }` - 允许助手使用统一差异创建、删除或更新文件。 + 允许助手使用 unified diff 创建、删除或更新文件。 - `type: "apply_patch"` - 工具的类型。始终 `apply_patch`. + 工具的类型。始终为 `apply_patch`. - `"apply_patch"` @@ -3163,28 +3163,28 @@ - `type: "additional_tools"` - 条目的类型。始终为 `additional_tools`. + 该项的类型。始终为 `additional_tools`. - `"additional_tools"` - `Reasoning object { id, summary, type, 3 more }` - 推理模型在生成 - 响应时使用的思维链描述。请务必将这些项目包含在你的 `input` 到 Responses API - 中，以便在手动 + 对推理模型在生成响应时所使用的思维链的描述。 + 如果你正在手动管理上下文，请务必将这些条目 `input` 包含到后续对话轮次的 Responses API + 请求中。 [管理上下文](/docs/guides/conversation-state). - `id: string` - 时用于对话的后续轮次。 + 推理内容的唯一标识符。 - `summary: array of SummaryTextContent` - 推理内容的唯一标识符。 + 推理摘要内容。 - `text: string` - 模型迄今为止的推理输出的摘要。 + 模型截至目前的推理输出摘要。 - `type: "summary_text"` @@ -3198,11 +3198,11 @@ - `content: optional array of object { text, type }` - 推理摘要内容。 + 推理文本内容。 - `text: string` - 模型的推理文本。 + 模型输出的推理文本。 - `type: "reasoning_text"` @@ -3212,20 +3212,20 @@ - `encrypted_content: optional string or null` - 推理文本内容。 - 推理项目的加密内容。默认情况下，对于由 `POST /v1/responses` 和 WebSocket - `response.create` 请求返回的推理项目，此字段会被填充。 + 推理条目的加密内容。默认情况下，该字段会由 + 以下方式返回的推理条目填充： `POST /v1/responses` 以及 WebSocket + `response.create` 请求。 - 流式传输时，使用已完成的推理项目及其 - `encrypted_content` 来自 `response.output_item.done` 事件，用于 - 后续请求。在 `encrypted_content` 中的 - `response.output_item.added` 可能不完整。这在 - 时尤其重要 `store` 是 `false` 或使用零数据保留时。 + 流式传输时，请在后续请求中使用已完成的推理条目及其 + `encrypted_content` 来自 `response.output_item.done` 事件。该 + 事件可能不完整。这一点在 `encrypted_content` 在 + `response.output_item.added` 时尤其重要。 + 需要时 `store` 在 `false` 或使用 Zero Data Retention 时。 - `status: optional "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。当项目通过 API 返回时填充。 + 条目的状态。可选值为 `in_progress`, `completed`，或 + `incomplete`。当通过 API 返回条目时填充。 - `"in_progress"` @@ -3237,23 +3237,23 @@ - `id: string` - 程序项的唯一 ID。 + 该程序项的唯一 ID。 - `call_id: string` - 程序项的稳定调用 ID。 + 该程序项的稳定调用 ID。 - `code: string` - 由程序化工具调用执行的 JavaScript 源代码。 + 由程序化工具调用执行的 JavaScript 源码。 - `fingerprint: string` - 不透明的程序重放指纹，必须原样返回。 + 必须往返传输的不透明程序回放指纹。 - `type: "program"` - 条目的类型。始终为 `program`. + 该项的类型。始终为 `program`. - `"program"` @@ -3261,19 +3261,19 @@ - `id: string` - 程序输出项的唯一 ID。 + 该程序输出项的唯一 ID。 - `call_id: string` - 程序项的调用 ID。 + 该程序项的调用 ID。 - `result: string` - 程序项产生的结果。 + 由该程序项生成的结果。 - `status: "completed" or "incomplete"` - 程序输出项的最终状态。 + 该程序输出项的最终状态。 - `"completed"` @@ -3281,7 +3281,7 @@ - `type: "program_output"` - 条目的类型。始终为 `program_output`. + 该项的类型。始终为 `program_output`. - `"program_output"` @@ -3291,29 +3291,29 @@ - `id: string` - 压缩项的唯一 ID。 + 该压缩项的唯一 ID。 - `encrypted_content: string` - 压缩产生的加密内容。 + 由压缩生成的内容（已加密）。 - `type: "compaction"` - 条目的类型。始终为 `compaction`. + 该项的类型。始终为 `compaction`. - `"compaction"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `CodeInterpreterCall object { id, code, container_id, 3 more }` - 运行代码的工具调用。 + 用于运行代码的工具调用。 - `id: string` - 代码解释器工具调用的唯一 ID。 + 该代码解释器工具调用的唯一 ID。 - `code: string or null` @@ -3321,20 +3321,20 @@ - `container_id: string` - 用于运行代码的容器 ID。 + 用于运行该代码的容器的 ID。 - `outputs: array of object { logs, type } or object { type, url } or null` - 代码解释器生成的输出，例如日志或图像。 - 如果没有可用的输出，则可为 null。 + 由代码解释器生成的输出，例如日志或图片。 + 如果没有可用输出，可以为 null。 - `Logs object { logs, type }` - 代码解释器输出的日志。 + 代码解释器的日志输出。 - `logs: string` - 代码解释器输出的日志。 + 代码解释器的日志输出。 - `type: "logs"` @@ -3344,7 +3344,7 @@ - `Image object { type, url }` - 代码解释器输出的图像。 + 代码解释器的图像输出。 - `type: "image"` @@ -3358,7 +3358,7 @@ - `status: "in_progress" or "completed" or "incomplete" or 2 more` - 代码解释器工具调用的状态。有效值为 `in_progress`, `completed`, `incomplete`, `interpreting`,以及 `failed`. + 代码解释器工具调用的状态。有效值为 `in_progress`, `completed`, `incomplete`, `interpreting`，以及 `failed`. - `"in_progress"` @@ -3386,7 +3386,7 @@ - `action: object { command, env, type, 3 more }` - 在服务器上执行 shell 命令。 + 在服务端执行 shell 命令。 - `command: array of string` @@ -3394,7 +3394,7 @@ - `env: map[string]` - 为命令设置的环境变量。 + 要为命令设置的环境变量。 - `type: "exec"` @@ -3408,11 +3408,11 @@ - `user: optional string or null` - 可选地，以指定用户身份运行命令。 + 运行命令时使用的可选用户。 - `working_directory: optional string or null` - 可选的工作目录，用于运行命令。 + 运行命令的可选工作目录。 - `call_id: string` @@ -3448,13 +3448,13 @@ - `type: "local_shell_call_output"` - 本地 shell 工具调用输出的类型。始终 `local_shell_call_output`. + 本地 shell 工具调用输出的类型。始终为 `local_shell_call_output`. - `"local_shell_call_output"` - `status: optional "in_progress" or "completed" or "incomplete" or null` - 项目的状态。以下之一： `in_progress`, `completed`，或 `incomplete`. + 条目的状态。可选值为 `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3468,21 +3468,21 @@ - `id: string` - shell 工具调用的唯一 ID。当此项目通过 API 返回时填充。 + shell 工具调用的唯一 ID。当通过 API 返回此条目时填充。 - `action: object { commands, max_output_length, timeout_ms }` - 描述如何运行此工具调用的 shell 命令和限制。 + 描述如何运行该工具调用的 shell 命令和限制。 - `commands: array of string` - `max_output_length: number or null` - 可选的最大字符数，用于限制每条命令的返回内容。 + 可选的每个命令返回的最大字符数。 - `timeout_ms: number or null` - 可选的命令超时时间（毫秒）。 + 命令的可选超时时间（毫秒）。 - `call_id: string` @@ -3490,15 +3490,15 @@ - `environment: ResponseLocalEnvironment or ResponseContainerReference or null` - 表示使用本地环境执行 shell 操作。 + 表示使用本地环境来执行 shell 操作。 - `ResponseLocalEnvironment object { type }` - 表示使用本地环境执行 shell 操作。 + 表示使用本地环境来执行 shell 操作。 - `type: "local"` - 环境类型。始终 `local`. + 环境类型。始终为 `local`. - `"local"` @@ -3510,13 +3510,13 @@ - `type: "container_reference"` - 环境类型。始终 `container_reference`. + 环境类型。始终为 `container_reference`. - `"container_reference"` - `status: "in_progress" or "completed" or "incomplete"` - shell 调用的状态。以下之一 `in_progress`, `completed`，或 `incomplete`. + shell 调用的状态。取值为 `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3526,7 +3526,7 @@ - `type: "shell_call"` - 条目的类型。始终为 `shell_call`. + 该项的类型。始终为 `shell_call`. - `"shell_call"` @@ -3544,7 +3544,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -3552,7 +3552,7 @@ - `created_by: optional string` - 创建此工具调用的实体的 ID。 + 创建此工具调用的实体 ID。 - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` @@ -3560,7 +3560,7 @@ - `id: string` - shell 调用输出的唯一 ID。当此项目通过 API 返回时填充。 + shell 调用输出的唯一 ID。当通过 API 返回此条目时填充。 - `call_id: string` @@ -3568,7 +3568,7 @@ - `max_output_length: number or null` - shell 命令输出的最大长度。此值由模型生成，应与原始输出一起传回。 + shell 命令输出的最大长度。该值由模型生成，应与原始输出一起传回。 - `output: array of object { outcome, stderr, stdout, created_by }` @@ -3576,21 +3576,21 @@ - `outcome: object { type } or object { exit_code, type }` - 表示 shell 调用输出块的退出结果（带退出码）或超时结果。 + 表示 shell 调用输出块的退出结果（带有退出码）或超时结果。 - `Timeout object { type }` - 表示 shell 调用超出其配置的时间限制。 + 表示 shell 调用超过了其配置的时间限制。 - `type: "timeout"` - 结果类型。始终 `timeout`. + 结果类型。始终为 `timeout`. - `"timeout"` - `Exit object { exit_code, type }` - 表示 shell 命令已完成并返回退出码。 + 表示 shell 命令已结束并返回了退出码。 - `exit_code: number` @@ -3598,25 +3598,25 @@ - `type: "exit"` - 结果类型。始终 `exit`. + 结果类型。始终为 `exit`. - `"exit"` - `stderr: string` - 捕获的标准错误输出。 + 捕获到的标准错误输出。 - `stdout: string` - 捕获的标准输出。 + 捕获到的标准输出。 - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `status: "in_progress" or "completed" or "incomplete"` - shell 调用输出的状态。取值为 `in_progress`, `completed`，或 `incomplete`. + shell 调用输出的状态。取值之一： `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3644,7 +3644,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -3652,19 +3652,19 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该项的行为者的标识符。 - `ApplyPatchCall object { id, call_id, operation, 4 more }` - 一种工具调用，通过创建、删除或更新文件来应用文件差异。 + 通过创建、删除或更新文件来应用文件差异的工具调用。 - `id: string` - apply patch 工具调用的唯一 ID。当此项通过 API 返回时填充。 + apply patch 工具调用的唯一 ID。当该条目通过 API 返回时填充。 - `call_id: string` - 由模型生成的 apply patch 工具调用的唯一 ID。 + 模型生成的 apply patch 工具调用的唯一 ID。 - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` @@ -3722,7 +3722,7 @@ - `status: "in_progress" or "completed"` - apply patch 工具调用的状态。取值为 `in_progress` 或 `completed`. + apply patch 工具调用的状态。取值之一： `in_progress` 或 `completed`. - `"in_progress"` @@ -3730,7 +3730,7 @@ - `type: "apply_patch_call"` - 条目的类型。始终为 `apply_patch_call`. + 该项的类型。始终为 `apply_patch_call`. - `"apply_patch_call"` @@ -3748,7 +3748,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -3756,23 +3756,23 @@ - `created_by: optional string` - 创建此工具调用的实体的 ID。 + 创建此工具调用的实体 ID。 - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - apply patch 工具调用产生的输出。 + apply patch 工具调用所输出的内容。 - `id: string` - apply patch 工具调用输出的唯一 ID。当此项通过 API 返回时填充。 + apply patch 工具调用输出的唯一 ID。当该条目通过 API 返回时填充。 - `call_id: string` - 由模型生成的 apply patch 工具调用的唯一 ID。 + 模型生成的 apply patch 工具调用的唯一 ID。 - `status: "completed" or "failed"` - apply patch 工具调用输出的状态。以下之一： `completed` 或 `failed`. + apply patch 工具调用输出的状态。取值之一为 `completed` 或 `failed`. - `"completed"` @@ -3780,7 +3780,7 @@ - `type: "apply_patch_call_output"` - 条目的类型。始终为 `apply_patch_call_output`. + 该项的类型。始终为 `apply_patch_call_output`. - `"apply_patch_call_output"` @@ -3798,7 +3798,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -3818,7 +3818,7 @@ - `id: string` - 列表的唯一 ID。 + 该列表的唯一 ID。 - `server_label: string` @@ -3830,7 +3830,7 @@ - `input_schema: unknown` - 描述工具输入的 JSON schema。 + 描述该工具输入的 JSON schema。 - `name: string` @@ -3838,7 +3838,7 @@ - `annotations: optional unknown or null` - 关于工具的附加注释。 + 有关该工具的额外注解。 - `description: optional string or null` @@ -3846,25 +3846,25 @@ - `type: "mcp_list_tools"` - 条目的类型。始终为 `mcp_list_tools`. + 该项的类型。始终为 `mcp_list_tools`. - `"mcp_list_tools"` - `error: optional string or null` - 如果服务器无法列出工具，则显示错误消息。 + 服务器无法列出工具时的错误信息。 - `McpApprovalRequest object { id, arguments, name, 2 more }` - 请求人工批准工具调用的请求。 + 对工具调用的人工审批请求。 - `id: string` - 批准请求的唯一 ID。 + 审批请求的唯一 ID。 - `arguments: string` - 工具参数的 JSON 字符串。 + 该工具参数的 JSON 字符串。 - `name: string` @@ -3872,17 +3872,17 @@ - `server_label: string` - 发出请求的 MCP 服务器的标签。 + 发起请求的 MCP 服务器的标签。 - `type: "mcp_approval_request"` - 条目的类型。始终为 `mcp_approval_request`. + 该项的类型。始终为 `mcp_approval_request`. - `"mcp_approval_request"` - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - 对 MCP 批准请求的响应。 + 对 MCP 审批请求的响应。 - `id: string` @@ -3890,25 +3890,25 @@ - `approval_request_id: string` - 所回答审批请求的 ID。 + 正在被答复的审批请求的 ID。 - `approve: boolean` - 该请求是否已获批准。 + 请求是否已批准。 - `type: "mcp_approval_response"` - 条目的类型。始终为 `mcp_approval_response`. + 该项的类型。始终为 `mcp_approval_response`. - `"mcp_approval_response"` - `reason: optional string or null` - 决策的可选原因。 + 可选的决策原因。 - `McpCall object { id, arguments, name, 6 more }` - 在 MCP 服务器上调用工具。 + 对 MCP 服务器上某个工具的调用。 - `id: string` @@ -3916,11 +3916,11 @@ - `arguments: string` - 传递给工具的参数的 JSON 字符串。 + 传递给该工具的参数的 JSON 字符串。 - `name: string` - 所运行工具的名称。 + 已运行的工具的名称。 - `server_label: string` @@ -3928,18 +3928,18 @@ - `type: "mcp_call"` - 条目的类型。始终为 `mcp_call`. + 该项的类型。始终为 `mcp_call`. - `"mcp_call"` - `approval_request_id: optional string or null` MCP 工具调用审批请求的唯一标识符。 - 在后续 `mcp_approval_response` 输入中包含此值，以批准或拒绝相应的工具调用。 + 在后续的 `mcp_approval_response` 输入中传入此值，以批准或拒绝相应的工具调用。 - `error: optional McpToolCallError or null` - 工具调用中的错误（如有）。 + 工具调用的错误（如果有）。 - `McpProtocolError object { code, message, type }` @@ -3975,7 +3975,7 @@ - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - 工具调用的状态。可为 `in_progress`, `completed`, `incomplete`, `calling`，或 `failed`. + 工具调用的状态，取值之一为 `in_progress`, `completed`, `incomplete`, `calling`，或 `failed`. - `"in_progress"` @@ -3997,21 +3997,21 @@ - `input: string` - 模型生成的自定义工具调用的输入。 + 由模型生成的自定义工具调用的输入。 - `name: string` - 所调用自定义工具的名称。 + 正在调用的自定义工具的名称。 - `type: "custom_tool_call"` - 自定义工具调用的类型。始终为 `custom_tool_call`. + 自定义工具调用的类型，始终为 `custom_tool_call`. - `"custom_tool_call"` - `id: optional string` - 自定义工具调用在 OpenAI 平台中的唯一 ID。 + OpenAI 平台上该自定义工具调用的唯一 ID。 - `caller: optional object { type } or object { caller_id, type } or null` @@ -4027,7 +4027,7 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` @@ -4039,15 +4039,15 @@ - `CustomToolCallOutput object { call_id, output, type, 2 more }` - 你的代码中自定义工具调用的输出，将被发送回模型。 + 来自你代码的自定义工具调用输出，正被发回给模型。 - `call_id: string` - 调用 ID，用于将此自定义工具调用输出映射到自定义工具调用。 + 调用 ID，用于将此自定义工具调用输出映射到对应的自定义工具调用。 - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 你的代码生成的自定义工具调用的输出。 + 由你的代码生成的自定义工具调用输出。 可以是字符串或输出内容列表。 - `StringOutput = string` @@ -4056,11 +4056,11 @@ - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 自定义工具调用的文本、图像或文件输出。 + 自定义工具调用的文本、图片或文件输出。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入到模型的文本。 + 发送给模型的文本输入。 - `ResponseInputImage object { detail, type, file_id, 2 more }` @@ -4078,7 +4078,7 @@ - `id: optional string` - 自定义工具调用输出在 OpenAI 平台中的唯一 ID。 + OpenAI 平台上该自定义工具调用输出的唯一 ID。 - `caller: optional object { type } or object { caller_id, type } or null` @@ -4088,7 +4088,7 @@ - `type: "direct"` - 调用者类型。始终为 `direct`. + 调用方类型。始终为 `direct`. - `"direct"` @@ -4096,11 +4096,11 @@ - `caller_id: string` - 产生此工具调用的程序项调用 ID。 + 产生此工具调用的程序项的调用 ID。 - `type: "program"` - 调用者类型。始终为 `program`. + 调用方类型。始终为 `program`. - `"program"` @@ -4118,7 +4118,7 @@ - `object: "list"` - 返回的对象类型，必须为 `list`. + 返回对象的类型，必须为 `list`. - `"list"` @@ -4129,7 +4129,7 @@ curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -4165,7 +4165,7 @@ curl "https://api.openai.com/v1/conversations/conv_123/items?limit=10" \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { diff --git a/docs/zh/api/reference/resources/evals/methods/create.md b/docs/zh/api/reference/resources/evals/methods/create.md index 372fc0f..4a0df16 100644 --- a/docs/zh/api/reference/resources/evals/methods/create.md +++ b/docs/zh/api/reference/resources/evals/methods/create.md @@ -1,30 +1,30 @@ -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。通过向页面 URL 追加 `.md` 可获取文档页面的 Markdown 版本。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾附加 `.md` 即可获取该页面的 Markdown 版本文档。 -## 创建评测 +## 创建评估 **post** `/evals` -创建评估的结构，该结构可用于测试模型的性能。 -评估是一组测试标准和一个数据源的配置，它决定了评估中所用数据的架构。创建评估后，你可以在不同的模型和模型参数上运行它。我们支持多种类型的评分器和数据源。 -更多信息，请参阅 [Evals 指南](/docs/guides/evals). +创建一个评估的结构，可用于测试模型的性能。 +一个评估是一组测试标准以及数据源的配置，它决定了评估中所用数据的 schema。在创建评估之后，你可以在不同的模型和模型参数上运行它。我们支持多种类型的评分器和数据源。 +有关更多信息，请参阅 [Evals guide](/docs/guides/evals). -### 请求体参数 +### 正文参数 - `data_source_config: object { item_schema, type, include_sample_schema } or object { type, metadata } or object { type, metadata }` - 用于评估运行的数据源的配置。决定评估中使用的数据的模式。 + 评估运行所用数据源的配置。用于规定评估中数据所遵循的架构。 - `CustomDataSourceConfig object { item_schema, type, include_sample_schema }` - 一个 CustomDataSourceConfig 对象，定义用于评估运行的数据源的模式。 - 此模式用于定义数据的形状，这些数据将： + 一个 CustomDataSourceConfig 对象，用于定义评估运行所用数据源的架构。 + 此架构用于定义以下数据的形态： - - 用于定义你的测试标准，以及 - - 创建运行时的必需数据 + - 用于定义你的测试条件，以及 + - 创建运行时需要哪些数据 - `item_schema: map[unknown]` - 数据源中每一行的 json 模式。 + 数据源中每一行的 json 架构。 - `type: "custom"` @@ -34,12 +34,12 @@ - `include_sample_schema: optional boolean` - 评估是否应期望你填充 sample 命名空间（即，通过基于你的数据源生成响应） + 评估是否应要求你填充样本命名空间（即通过根据数据源生成响应） - `LogsDataSourceConfig object { type, metadata }` - 一个数据源配置，指定你的日志查询的 metadata 属性。 - 这通常是元数据，如 `usecase=chatbot` 或 `prompt-version=v2`，等。 + 用于指定日志查询元数据属性的数据源配置。 + 通常为如下元数据： `usecase=chatbot` 或 `prompt-version=v2`，等。 - `type: "logs"` @@ -49,11 +49,11 @@ - `metadata: optional map[unknown]` - 日志数据源的元数据过滤器。 + 日志数据源的元数据筛选条件。 - `StoredCompletionsDataSourceConfig object { type, metadata }` - 已弃用，改用 LogsDataSourceConfig。 + 已弃用，推荐使用 LogsDataSourceConfig。 - `type: "stored_completions"` @@ -63,20 +63,20 @@ - `metadata: optional map[unknown]` - 已存储补全数据源的元数据过滤器。 + 存储补全数据源的元数据筛选条件。 - `testing_criteria: array of object { input, labels, model, 3 more } or StringCheckGrader or TextSimilarityGrader or 2 more` - 此组中所有评估运行的评分器列表。评分器可以使用双花括号符号引用数据源中的变量，例如 `{{item.variable_name}}`。要引用模型的输出，请使用 `sample` 命名空间（即， `{{sample.output_text}}`). + 此组中所有评估运行的评分器列表。评分器可以使用双花括号表示法引用数据源中的变量，例如 `{{item.variable_name}}`。要引用模型的输出，请使用 `sample` 命名空间（即， `{{sample.output_text}}`). - `LabelModelGrader object { input, labels, model, 3 more }` - 一个 LabelModelGrader 对象，使用模型为评估中的每个项目分配标签 + 一个 LabelModelGrader 对象，使用模型为每个评估项分配标签 。 - `input: array of object { content, role } or object { content, role, type }` - 构成提示或上下文的聊天消息列表。可能包含对 `item` 命名空间的变量引用，即 {{item.name}}。 + 构成提示词或上下文的聊天消息列表。可以包含对 `item` 命名空间的变量引用，例如 {{item.name}}。 - `SimpleInputMessage object { content, role }` @@ -90,37 +90,37 @@ - `EvalMessageObject object { content, role, type }` - 输入给模型的消息，其角色指示指令遵循 - 层级。使用 `developer` 或 `system` 角色给出的指令 + 输入到模型的消息，其角色用于表示指令的 + 层级关系。使用 `developer` 或 `system` 角色给出的指令 优先于使用 `user` 角色给出的指令。使用 `assistant` 角色的消息被视为模型在之前的 - 交互中生成的。 + 交互中生成的内容。 - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以作为单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项，也可以是项的数组。 - `TextInput = string` - 对模型的文本输入。 + 模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `text: string` - 对模型的文本输入。 + 模型的文本输入。 - `type: "input_text"` - 输入项目的类型。始终为 `input_text`. + 输入项的类型。始终为 `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结束位置。断点继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会四舍五入到标记块。 + 标记可复用提示前缀的精确结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 - `mode: "explicit"` @@ -144,7 +144,7 @@ - `InputImage object { image_url, type, detail }` - 在 EvalItem 内容数组内使用的图像输入块。 + EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -158,7 +158,7 @@ - `detail: optional string` - 发送给模型的图像的细节级别。取值为 `high`, `low`、 `auto`，默认为 `auto`. + 要发送到模型的图像详细程度级别。取值为 `high`, `low`、或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` @@ -181,22 +181,22 @@ - `type: "input_audio"` - 输入项目的类型。始终为 `input_audio`. + 输入项的类型。始终为 `input_audio`. - `"input_audio"` - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入列表，其中每一项可以是输入文本、输出文本、输入 + 输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 对模型的文本输入。 + 模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `OutputText object { text, type }` @@ -214,7 +214,7 @@ - `InputImage object { image_url, type, detail }` - 在 EvalItem 内容数组内使用的图像输入块。 + EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -228,7 +228,7 @@ - `detail: optional string` - 发送给模型的图像的细节级别。取值为 `high`, `low`、 `auto`，默认为 `auto`. + 要发送到模型的图像详细程度级别。取值为 `high`, `low`、或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` @@ -236,7 +236,7 @@ - `role: "user" or "assistant" or "system" or "developer"` - 消息输入的角色。取值为 `user`, `assistant`, `system`、 + 消息输入的角色。取值为 `user`, `assistant`, `system`、或 `developer`. - `"user"` @@ -255,7 +255,7 @@ - `labels: array of string` - 用于对评估中的每个项目进行分类的标签。 + 要分类到评估中每个项目的标签。 - `model: string` @@ -267,7 +267,7 @@ - `passing_labels: array of string` - 表示通过结果的标签。必须是标签的子集。 + 表示通过结果的标签。必须是标签集合的子集。 - `type: "label_model"` @@ -277,11 +277,11 @@ - `StringCheckGrader object { input, name, operation, 2 more }` - 一个 StringCheckGrader 对象，使用指定的操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作对输入和参考答案进行字符串比较。 - `input: string` - 输入文本。这可能包括模板字符串。 + 输入文本。可以包含模板字符串。 - `name: string` @@ -289,7 +289,7 @@ - `operation: "eq" or "ne" or "like" or "ilike"` - 要执行的字符串检查操作。以下之一 `eq`, `ne`, `like`、 `ilike`. + 要执行的字符串检查操作。可选值之一 `eq`, `ne`, `like`、或 `ilike`. - `"eq"` @@ -301,7 +301,7 @@ - `reference: string` - 参考文本。这可能包括模板字符串。 + 参考答案文本。可以包含模板字符串。 - `type: "string_check"` @@ -311,67 +311,67 @@ - `TextSimilarity = TextSimilarityGrader` - 一个 TextSimilarityGrader 对象，根据相似度指标对文本评分。 + 一个 TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 - `pass_threshold: number` - 评分的阈值。 + 分数阈值。 - `Python = PythonGrader` - 一个 PythonGrader 对象，对输入运行 python 脚本。 + 一个 PythonGrader 对象，对输入运行 Python 脚本。 - `pass_threshold: optional number` - 评分的阈值。 + 分数阈值。 - `ScoreModel = ScoreModelGrader` - 一个 ScoreModelGrader 对象，使用模型为输入分配分数。 + 一个 ScoreModelGrader 对象，使用模型为输入打分。 - `pass_threshold: optional number` - 评分的阈值。 + 分数阈值。 - `metadata: optional Metadata or null` - 可以附加到对象上的 16 组键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， + 可以附加到对象的 16 个键值对。这可以 + 用于以结构化格式存储关于对象的附加信息， 并通过 API 或仪表板查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - 最大长度为 512 个字符。 + 键是字符串，最长 64 个字符。值是字符串， + 最长 512 个字符。 - `name: optional string` 评估的名称。 -### 返回 +### Returns - `id: string` - 评估的唯一标识符。 + 该评估的唯一标识符。 - `created_at: number` - 创建评估时的 Unix 时间戳（以秒为单位）。 + 评估创建时的 Unix 时间戳（以秒为单位）。 - `data_source_config: EvalCustomDataSourceConfig or object { schema, type, metadata } or EvalStoredCompletionsDataSourceConfig` - 评估运行中使用的数据源配置。 + 评估运行中所使用的数据源配置。 - `EvalCustomDataSourceConfig object { schema, type }` - 一个 CustomDataSourceConfig，用于指定你 `item` 以及可选的 `sample` 命名空间。 - 响应模式定义了将数据形状： + 一个 CustomDataSourceConfig，用于指定你的 `item` 以及可选的 `sample` 命名空间。 + 响应模式定义了数据将呈现的以下形状： - - 用于定义你的测试标准，以及 - - 创建运行时的必需数据 + - 用于定义你的测试条件，以及 + - 创建运行时需要哪些数据 - `schema: map[unknown]` - 运行数据源项的 JSON 模式。 - 了解如何构建 JSON 模式 [此处](https://json-schema.org/). + 运行数据源项的 json 模式。 + 了解如何构建 JSON 模式 [请参考此处](https://json-schema.org/). - `type: "custom"` @@ -381,15 +381,15 @@ - `LogsDataSourceConfig object { schema, type, metadata }` - 一个 LogsDataSourceConfig，用于指定日志查询的元数据属性。 - 这通常是元数据，如 `usecase=chatbot` 或 `prompt-version=v2`，等。 + 一个 LogsDataSourceConfig，用于指定你日志查询的元数据属性。 + 通常为如下元数据： `usecase=chatbot` 或 `prompt-version=v2`，等。 此数据源配置返回的模式用于定义评估中可用的变量。 - `item` 和 `sample` 在使用此数据源配置时均已定义。 + `item` 和 `sample` 在使用此数据源配置时都会被定义。 - `schema: map[unknown]` - 运行数据源项的 JSON 模式。 - 了解如何构建 JSON 模式 [此处](https://json-schema.org/). + 运行数据源项的 json 模式。 + 了解如何构建 JSON 模式 [请参考此处](https://json-schema.org/). - `type: "logs"` @@ -399,21 +399,21 @@ - `metadata: optional Metadata or null` - 可以附加到对象上的 16 组键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， + 可以附加到对象的 16 个键值对。这可以 + 用于以结构化格式存储关于对象的附加信息， 并通过 API 或仪表板查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - 最大长度为 512 个字符。 + 键是字符串，最长 64 个字符。值是字符串， + 最长 512 个字符。 - `EvalStoredCompletionsDataSourceConfig object { schema, type, metadata }` - 已弃用，改用 LogsDataSourceConfig。 + 已弃用，推荐使用 LogsDataSourceConfig。 - `schema: map[unknown]` - 运行数据源项的 JSON 模式。 - 了解如何构建 JSON 模式 [此处](https://json-schema.org/). + 运行数据源项的 json 模式。 + 了解如何构建 JSON 模式 [请参考此处](https://json-schema.org/). - `type: "stored_completions"` @@ -423,21 +423,21 @@ - `metadata: optional Metadata or null` - 可以附加到对象上的 16 组键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， + 可以附加到对象的 16 个键值对。这可以 + 用于以结构化格式存储关于对象的附加信息， 并通过 API 或仪表板查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - 最大长度为 512 个字符。 + 键是字符串，最长 64 个字符。值是字符串， + 最长 512 个字符。 - `metadata: Metadata or null` - 可以附加到对象上的 16 组键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， + 可以附加到对象的 16 个键值对。这可以 + 用于以结构化格式存储关于对象的附加信息， 并通过 API 或仪表板查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - 最大长度为 512 个字符。 + 键是字符串，最长 64 个字符。值是字符串， + 最长 512 个字符。 - `name: string` @@ -451,40 +451,40 @@ - `testing_criteria: array of LabelModelGrader or StringCheckGrader or TextSimilarityGrader or 2 more` - 测试标准列表。 + 测试条件列表。 - `LabelModelGrader object { input, labels, model, 3 more }` - 一个 LabelModelGrader 对象，使用模型为评估中的每个项目分配标签 + 一个 LabelModelGrader 对象，使用模型为每个评估项分配标签 。 - `input: array of object { content, role, type }` - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以作为单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项，也可以是项的数组。 - `TextInput = string` - 对模型的文本输入。 + 模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `text: string` - 对模型的文本输入。 + 模型的文本输入。 - `type: "input_text"` - 输入项目的类型。始终为 `input_text`. + 输入项的类型。始终为 `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结束位置。断点继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会四舍五入到标记块。 + 标记可复用提示前缀的精确结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 - `mode: "explicit"` @@ -508,7 +508,7 @@ - `InputImage object { image_url, type, detail }` - 在 EvalItem 内容数组内使用的图像输入块。 + EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -522,7 +522,7 @@ - `detail: optional string` - 发送给模型的图像的细节级别。取值为 `high`, `low`、 `auto`，默认为 `auto`. + 要发送到模型的图像详细程度级别。取值为 `high`, `low`、或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` @@ -545,22 +545,22 @@ - `type: "input_audio"` - 输入项目的类型。始终为 `input_audio`. + 输入项的类型。始终为 `input_audio`. - `"input_audio"` - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入列表，其中每一项可以是输入文本、输出文本、输入 + 输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 对模型的文本输入。 + 模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `OutputText object { text, type }` @@ -578,7 +578,7 @@ - `InputImage object { image_url, type, detail }` - 在 EvalItem 内容数组内使用的图像输入块。 + EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -592,7 +592,7 @@ - `detail: optional string` - 发送给模型的图像的细节级别。取值为 `high`, `low`、 `auto`，默认为 `auto`. + 要发送到模型的图像详细程度级别。取值为 `high`, `low`、或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` @@ -600,7 +600,7 @@ - `role: "user" or "assistant" or "system" or "developer"` - 消息输入的角色。取值为 `user`, `assistant`, `system`、 + 消息输入的角色。取值为 `user`, `assistant`, `system`、或 `developer`. - `"user"` @@ -619,7 +619,7 @@ - `labels: array of string` - 要分配给评估中每个项目的标签。 + 分配给评估中每个项的标签。 - `model: string` @@ -631,7 +631,7 @@ - `passing_labels: array of string` - 表示通过结果的标签。必须是标签的子集。 + 表示通过结果的标签。必须是标签集合的子集。 - `type: "label_model"` @@ -641,11 +641,11 @@ - `StringCheckGrader object { input, name, operation, 2 more }` - 一个 StringCheckGrader 对象，使用指定的操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作对输入和参考答案进行字符串比较。 - `input: string` - 输入文本。这可能包括模板字符串。 + 输入文本。可以包含模板字符串。 - `name: string` @@ -653,7 +653,7 @@ - `operation: "eq" or "ne" or "like" or "ilike"` - 要执行的字符串检查操作。以下之一 `eq`, `ne`, `like`、 `ilike`. + 要执行的字符串检查操作。可选值之一 `eq`, `ne`, `like`、或 `ilike`. - `"eq"` @@ -665,7 +665,7 @@ - `reference: string` - 参考文本。这可能包括模板字符串。 + 参考答案文本。可以包含模板字符串。 - `type: "string_check"` @@ -675,27 +675,27 @@ - `TextSimilarityGrader = TextSimilarityGrader` - 一个 TextSimilarityGrader 对象，根据相似度指标对文本评分。 + 一个 TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 - `pass_threshold: number` - 评分的阈值。 + 分数阈值。 - `PythonGrader = PythonGrader` - 一个 PythonGrader 对象，对输入运行 python 脚本。 + 一个 PythonGrader 对象，对输入运行 Python 脚本。 - `pass_threshold: optional number` - 评分的阈值。 + 分数阈值。 - `ScoreModelGrader = ScoreModelGrader` - 一个 ScoreModelGrader 对象，使用模型为输入分配分数。 + 一个 ScoreModelGrader 对象，使用模型为输入打分。 - `pass_threshold: optional number` - 评分的阈值。 + 分数阈值。 ### 示例 diff --git a/docs/zh/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md b/docs/zh/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md index ce06a51..f2d3c63 100644 --- a/docs/zh/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md +++ b/docs/zh/api/reference/resources/fine_tuning/subresources/jobs/methods/list.md @@ -1,8 +1,8 @@ -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾追加 `.md` 即可获取该页面的 Markdown 版本。 -## 列出微调作业 +## 列出微调任务 -**获取** `/fine_tuning/jobs` +**get** `/fine_tuning/jobs` 列出你组织的微调作业 @@ -10,31 +10,31 @@ - `after: optional string` - 上一次分页请求中最后一个任务的标识符。 + 上一次分页请求中最后一个作业的标识符。 - `limit: optional number` - 要检索的微调任务数量。 + 要检索的微调作业数量。 - `metadata: optional map[string] or null` - 可选的元数据过滤器。要过滤，请使用语法 `metadata[k]=v`。或者，设置 `metadata=null` 以表示无元数据。 + 可选的元数据筛选器。要进行筛选，请使用语法 `metadata[k]=v`。或者，设置为 `metadata=null` 以表示没有元数据。 -### 返回 +### Returns - `data: array of FineTuningJob` - `id: string` - 对象标识符，可在API端点中引用。 + 对象标识符，可在 API 端点中引用。 - `created_at: number` - 创建微调作业时的 Unix 时间戳（以秒为单位）。 + 微调任务创建时的 Unix 时间戳（以秒为单位）。 - `error: object { code, message, param } or null` - 对于已 `failed`，的微调作业，此处将包含有关失败原因的更多信息。 + 对于已 `failed`，的微调任务，此字段将包含有关失败原因的更多信息。 - `code: string` @@ -46,24 +46,24 @@ - `param: string or null` - 无效的参数，通常是 `training_file` 或 `validation_file`。如果失败与参数无关，此字段将为 null。 + 无效的参数，通常为 `training_file` 或 `validation_file`。如果失败并非由特定参数导致，此字段将为 null。 - `fine_tuned_model: string or null` - 正在创建的微调模型的名称。如果微调作业仍在运行，该值将为 null。 + 正在创建的微调模型的名称。如果微调任务仍在运行，则该值为 null。 - `finished_at: number or null` - 微调作业完成时的 Unix 时间戳（以秒为单位）。如果微调作业仍在运行，该值将为 null。 + 微调任务完成时的 Unix 时间戳（以秒为单位）。如果微调任务仍在运行，则该值为 null。 - `hyperparameters: object { batch_size, learning_rate_multiplier, n_epochs }` - 用于微调作业的超参数。仅当运行 `supervised` 作业时才会返回此值。 + 用于微调任务的超参数。仅当运行 `supervised` 任务时才会返回此值。 - `batch_size: optional "auto" or number or null` - 每个批次中的示例数量。较大的批次大小意味着模型参数 - 更新的频率较低，但方差较小。 + 每个批次中的样本数量。更大的批量大小意味着模型参数 + 更新的频率更低，但方差更小。 - `"auto"` @@ -73,7 +73,7 @@ - `learning_rate_multiplier: optional "auto" or number` - 学习率的缩放因子。较小的学习率可能有助于避免 + 学习率的缩放因子。使用较小的学习率可能有助于避免 过拟合。 - `"auto"` @@ -84,8 +84,8 @@ - `n_epochs: optional "auto" or number` - 训练模型的周期数。一个周期指完整遍历 - 训练数据集一次。 + 训练模型的轮次（epoch）数。一个 epoch 指对训练数据集进行 + 一次完整遍历。 - `"auto"` @@ -95,7 +95,7 @@ - `model: string` - 正在被微调的基础模型。 + 正在进行微调的基础模型。 - `object: "fine_tuning.job"` @@ -105,19 +105,19 @@ - `organization_id: string` - 拥有该微调作业的组织。 + 拥有该微调任务的所有组织。 - `result_files: array of string` - 微调作业的已编译结果文件 ID。你可以通过以下方式检索结果： [Files API](/docs/api-reference/files/retrieve-contents). + 该微调任务的编译结果文件 ID。你可以使用 [Files API](/docs/api-reference/files/retrieve-contents). - `seed: number` - 用于微调作业的种子。 + 该微调任务使用的随机种子。 - `status: "validating_files" or "queued" or "running" or 3 more` - 微调作业的当前状态，可以是 `validating_files`, `queued`, `running`, `succeeded`, `failed`，或 `cancelled`. + 该微调任务的当前状态，可为 `validating_files`, `queued`, `running`, `succeeded`, `failed`，或 `cancelled`. - `"validating_files"` @@ -133,19 +133,19 @@ - `trained_tokens: number or null` - 此微调作业处理的可计费 token 总数。如果微调作业仍在运行，该值将为 null。 + 此微调任务处理的计费 token 总数。如果微调任务仍在运行，则该值为 null。 - `training_file: string` - 用于训练的文件 ID。你可以通过以下方式检索训练数据： [Files API](/docs/api-reference/files/retrieve-contents). + 用于训练的文件 ID。你可以使用 [Files API](/docs/api-reference/files/retrieve-contents). - `validation_file: string or null` - 用于验证的文件 ID。你可以通过以下方式检索验证结果： [Files API](/docs/api-reference/files/retrieve-contents). + 用于验证的文件 ID。你可以使用 [Files API](/docs/api-reference/files/retrieve-contents). - `estimated_finish: optional number or null` - 微调作业预计完成的 Unix 时间戳（秒）。如果微调作业未在运行，该值将为 null。 + 微调作业预计完成的 Unix 时间戳（以秒为单位）。如果微调作业未在运行，则该值为 null。 - `integrations: optional array of FineTuningJobWandbIntegrationObject or null` @@ -159,18 +159,18 @@ - `wandb: FineTuningJobWandbIntegration` - 用于与 Weights and Biases 集成的设置。此负载指定了指标将发送到的 - 项目。可选地，你可以为运行设置显式显示名称、为运行添加标签， - 并设置要与运行关联的默认实体（团队、用户名等）。 + 与 Weights and Biases 集成的设置。此负载指定将指标发送到的项目。 + 你可以选择为运行设置显式显示名称，并添加标签 + 添加到你的运行，并设置一个默认实体（团队、用户名等）来关联你的运行。 - `project: string` - 新运行将在其下创建的项目的名称。 + 新运行将在其下创建的项目名称。 - `entity: optional string or null` - 用于运行的实体。这允许你设置希望与运行关联的 WandB 用户的团队或用户名。 - 如果未设置，将使用注册的 WandB API 密钥的默认实体。 + 运行要使用的实体。这允许你设置要与运行关联的 WandB 用户的团队或用户名，你 + 希望关联运行。如果未设置，则使用已注册 WandB API 密钥的默认实体。 - `name: optional string or null` @@ -178,17 +178,17 @@ - `tags: optional array of string` - 要附加到新创建运行的一组标签。这些标签会直接传递给 WandB。部分 - OpenAI会生成默认标签："openai/finetune"、"openai/{base-model}"、"openai/{ftjob-abcdef}". + 要附加到新创建运行的一组标签。这些标签会直接传递给 WandB。某些 + 默认标签由 OpenAI 生成："openai/finetune"、"openai/{base-model}"、"openai/{ftjob-abcdef}". - `metadata: optional Metadata or null` - 可附加到对象上的16个键值对集合。这可以 - 用于以结构化格式存储有关对象的额外信息， - 并通过API或仪表板查询对象。 + 一组可附加到对象的 16 个键值对。这可以 + 用于以结构化格式存储有关对象的附加信息， + 并通过 API 或仪表板查询对象。 - 键是字符串，最大长度为64个字符。值是字符串 - ，最大长度为512个字符。 + 键为字符串，最大长度为 64 个字符。值为字符串， + 最大长度为 512 个字符。 - `method: optional object { type, dpo, reinforcement, supervised }` @@ -196,7 +196,7 @@ - `type: "supervised" or "dpo" or "reinforcement"` - 方法的类型。可以是 `supervised`, `dpo`，或 `reinforcement`. + 方法的类型。是 `supervised`, `dpo`，或 `reinforcement`. - `"supervised"` @@ -206,15 +206,15 @@ - `dpo: optional DpoMethod` - DPO微调方法的配置。 + DPO 微调方法的配置。 - `hyperparameters: optional DpoHyperparameters` - 用于DPO微调作业的超参数。 + 用于 DPO 微调作业的超参数。 - `batch_size: optional "auto" or number` - 每个批次中的示例数量。较大的批次大小意味着模型参数更新的频率较低，但方差较小。 + 每个批次中的示例数量。较大的批大小意味着模型参数更新频率降低，但方差也更低。 - `"auto"` @@ -224,7 +224,7 @@ - `beta: optional "auto" or number` - DPO方法的beta值。较高的beta值会增加策略模型与参考模型之间惩罚的权重。 + DPO 方法的 beta 值。较高的 beta 值会增大策略模型与参考模型之间惩罚项的权重。 - `"auto"` @@ -234,7 +234,7 @@ - `learning_rate_multiplier: optional "auto" or number` - 学习率的缩放因子。较小的学习率可能有助于避免过拟合。 + 学习率的缩放因子。使用较小的学习率可能有助于避免过拟合。 - `"auto"` @@ -244,7 +244,7 @@ - `n_epochs: optional "auto" or number` - 训练模型的轮数。一轮是指对训练数据集进行的一次完整循环。 + 训练模型的轮次数。一个 epoch 指的是对训练数据集进行一次完整的遍历。 - `"auto"` @@ -262,11 +262,11 @@ - `StringCheckGrader object { input, name, operation, 2 more }` - 一个StringCheckGrader对象，使用指定的操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作对输入和参考进行字符串比较。 - `input: string` - 输入文本。这可能包含模板字符串。 + 输入文本。可以包含模板字符串。 - `name: string` @@ -274,7 +274,7 @@ - `operation: "eq" or "ne" or "like" or "ilike"` - 要执行的字符串检查操作。可选值之一： `eq`, `ne`, `like`，或 `ilike`. + 要执行的字符串检查操作。取值为以下之一 `eq`, `ne`, `like`，或 `ilike`. - `"eq"` @@ -286,7 +286,7 @@ - `reference: string` - 参考文本。可能包含模板字符串。 + 参考文本。可以包含模板字符串。 - `type: "string_check"` @@ -300,7 +300,7 @@ - `evaluation_metric: "cosine" or "fuzzy_match" or "bleu" or 8 more` - 要使用的评估指标。可选值之一： `cosine`, `fuzzy_match`, `bleu`, + 要使用的评估指标。取值为以下之一 `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, 或 `rouge_l`. @@ -328,7 +328,7 @@ - `input: string` - 正在被评分的文本。 + 被评分的文本。 - `name: string` @@ -336,7 +336,7 @@ - `reference: string` - 用于对照评分的文本。 + 作为评分参照的文本。 - `type: "text_similarity"` @@ -346,7 +346,7 @@ - `PythonGrader object { name, source, type, image_tag }` - 一个 PythonGrader 对象，对输入运行 python 脚本。 + 一个 PythonGrader 对象，对输入运行 Python 脚本。 - `name: string` @@ -354,7 +354,7 @@ - `source: string` - python 脚本的源代码。 + Python 脚本的源代码。 - `type: "python"` @@ -364,31 +364,31 @@ - `image_tag: optional string` - 用于 python 脚本的镜像标签。 + Python 脚本所使用的镜像标签。 - `ScoreModelGrader object { input, model, name, 3 more }` - 一个 ScoreModelGrader 对象，使用模型为输入分配分数。 + 一个 ScoreModelGrader 对象，使用一个模型为输入打分。 - `input: array of object { content, role, type }` - 评分器评估的输入消息。支持文本、输出文本、输入图像和输入音频内容块，可能包含模板字符串。 + 由评分器评估的输入消息。支持文本、输出文本、输入图像和输入音频内容块，并可以包含模板字符串。 - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单项或项数组。 + 提供给模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可作为单个项或项的数组。 - `TextInput = string` - 模型的文本输入。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 提供给模型的文本输入。 - `text: string` - 模型的文本输入。 + 提供给模型的文本输入。 - `type: "input_text"` @@ -398,11 +398,11 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结束位置。断点继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会四舍五入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` - 断点模式。始终 `explicit`. + 断点模式。始终为 `explicit`. - `"explicit"` @@ -416,13 +416,13 @@ - `type: "output_text"` - 输出文本的类型。始终 `output_text`. + 输出文本的类型。始终为 `output_text`. - `"output_text"` - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -430,17 +430,17 @@ - `type: "input_image"` - 图像输入的类型。始终 `input_image`. + 图像输入的类型。始终为 `input_image`. - `"input_image"` - `detail: optional string` - 发送给模型的图像的细节级别。以下之一 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像的细节级别。可选值为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 模型的音频输入。 + 发送给模型的音频输入。 - `input_audio: object { data, format }` @@ -465,16 +465,16 @@ - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入列表，每一项可以是输入文本、输出文本、输入 + 输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 模型的文本输入。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -486,13 +486,13 @@ - `type: "output_text"` - 输出文本的类型。始终 `output_text`. + 输出文本的类型。始终为 `output_text`. - `"output_text"` - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -500,21 +500,21 @@ - `type: "input_image"` - 图像输入的类型。始终 `input_image`. + 图像输入的类型。始终为 `input_image`. - `"input_image"` - `detail: optional string` - 发送给模型的图像的细节级别。以下之一 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像的细节级别。可选值为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 模型的音频输入。 + 发送给模型的音频输入。 - `role: "user" or "assistant" or "system" or "developer"` - 消息输入的角色。以下之一 `user`, `assistant`, `system`，或 + 消息输入的角色。可选值为 `user`, `assistant`, `system`，或 `developer`. - `"user"` @@ -527,7 +527,7 @@ - `type: optional "message"` - 消息输入的类型。始终 `message`. + 消息输入的类型。始终为 `message`. - `"message"` @@ -547,7 +547,7 @@ - `range: optional array of number` - 分数的范围。默认为 `[0, 1]`. + 分数的取值范围。默认为 `[0, 1]`. - `sampling_params: optional object { max_completions_tokens, reasoning_effort, seed, 2 more }` @@ -559,13 +559,13 @@ - `reasoning_effort: optional ReasoningEffort or null` - 限制推理模型在推理上的投入。当前支持 - 的值为 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. - 降低推理投入可导致更快的响应和更少的 token - 用于响应中的推理。并非所有推理模型都支持每个 - 值。请参阅 + 约束推理模型在推理上的投入程度。目前支持 + 的取值有 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. + 降低推理投入程度可以让响应更快，并减少在响应中用于推理的 token + 数量。并非所有推理模型都支持每一个 + 取值。请参阅 [推理指南](https://platform.openai.com/docs/guides/reasoning) - 以了解模型特定支持。 + 以了解各模型的具体支持情况。 - `"none"` @@ -583,31 +583,31 @@ - `seed: optional number or null` - 用于初始化采样随机性的种子值。 + 用于在采样过程中初始化随机性的种子值。 - `temperature: optional number or null` - 较高的温度会增加输出的随机性。 + 较高的 temperature 会增加输出中的随机性。 - `top_p: optional number or null` - 使用核采样时替代温度的一种方式；1.0 包含所有 token。 + 用于核采样的 temperature 的替代方案；1.0 表示包含所有 token。 - `MultiGrader object { calculate_output, graders, name, type }` - MultiGrader 对象组合多个评分器的输出以产生单一分数。 + MultiGrader 对象将多个评分器的输出合并为单一分数。 - `calculate_output: string` - 根据评分器结果计算输出的公式。 + 用于根据评分器结果计算输出的公式。 - `graders: StringCheckGrader or TextSimilarityGrader or PythonGrader or 2 more` - 一个StringCheckGrader对象，使用指定的操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作对输入和参考进行字符串比较。 - `StringCheckGrader object { input, name, operation, 2 more }` - 一个StringCheckGrader对象，使用指定的操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作对输入和参考进行字符串比较。 - `TextSimilarityGrader object { evaluation_metric, input, name, 2 more }` @@ -615,30 +615,30 @@ - `PythonGrader object { name, source, type, image_tag }` - 一个 PythonGrader 对象，对输入运行 python 脚本。 + 一个 PythonGrader 对象，对输入运行 Python 脚本。 - `ScoreModelGrader object { input, model, name, 3 more }` - 一个 ScoreModelGrader 对象，使用模型为输入分配分数。 + 一个 ScoreModelGrader 对象，使用一个模型为输入打分。 - `LabelModelGrader object { input, labels, model, 3 more }` - LabelModelGrader 对象，使用模型为评估中的每个项目 + 一个 LabelModelGrader 对象，使用模型为评估中的每个条目 分配标签。 - `input: array of object { content, role, type }` - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单项或项数组。 + 提供给模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可作为单个项或项的数组。 - `TextInput = string` - 模型的文本输入。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -650,13 +650,13 @@ - `type: "output_text"` - 输出文本的类型。始终 `output_text`. + 输出文本的类型。始终为 `output_text`. - `"output_text"` - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -664,26 +664,26 @@ - `type: "input_image"` - 图像输入的类型。始终 `input_image`. + 图像输入的类型。始终为 `input_image`. - `"input_image"` - `detail: optional string` - 发送给模型的图像的细节级别。以下之一 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像的细节级别。可选值为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 模型的音频输入。 + 发送给模型的音频输入。 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入列表，每一项可以是输入文本、输出文本、输入 + 输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `role: "user" or "assistant" or "system" or "developer"` - 消息输入的角色。以下之一 `user`, `assistant`, `system`，或 + 消息输入的角色。可选值为 `user`, `assistant`, `system`，或 `developer`. - `"user"` @@ -696,17 +696,17 @@ - `type: optional "message"` - 消息输入的类型。始终 `message`. + 消息输入的类型。始终为 `message`. - `"message"` - `labels: array of string` - 评估中每个项目要分配的标签。 + 要分配给评估中每个条目的标签。 - `model: string` - 用于评估的模型。必须支持结构化输出。 + 用于评估的模型，必须支持结构化输出。 - `name: string` @@ -714,7 +714,7 @@ - `passing_labels: array of string` - 表示通过结果的标签。必须是标签的子集。 + 表示通过的标签，必须是 labels 的子集。 - `type: "label_model"` @@ -734,11 +734,11 @@ - `hyperparameters: optional ReinforcementHyperparameters` - 强化微调作业使用的超参数。 + 用于强化微调任务的超参数。 - `batch_size: optional "auto" or number` - 每个批次中的示例数量。较大的批次大小意味着模型参数更新的频率较低，但方差较小。 + 每个批次中的示例数量。较大的批大小意味着模型参数更新频率降低，但方差也更低。 - `"auto"` @@ -748,7 +748,7 @@ - `compute_multiplier: optional "auto" or number` - 训练期间用于探索搜索空间的计算量乘数。 + 训练期间用于探索搜索空间的算力乘数。 - `"auto"` @@ -778,7 +778,7 @@ - `learning_rate_multiplier: optional "auto" or number` - 学习率的缩放因子。较小的学习率可能有助于避免过拟合。 + 学习率的缩放因子。使用较小的学习率可能有助于避免过拟合。 - `"auto"` @@ -788,7 +788,7 @@ - `n_epochs: optional "auto" or number` - 训练模型的轮数。一轮是指对训练数据集进行的一次完整循环。 + 训练模型的轮次数。一个 epoch 指的是对训练数据集进行一次完整的遍历。 - `"auto"` @@ -798,7 +798,7 @@ - `reasoning_effort: optional "default" or "low" or "medium" or "high"` - 推理努力程度。 + 推理力度级别。 - `"default"` @@ -818,7 +818,7 @@ - `batch_size: optional "auto" or number` - 每个批次中的示例数量。较大的批次大小意味着模型参数更新的频率较低，但方差较小。 + 每个批次中的示例数量。较大的批大小意味着模型参数更新频率降低，但方差也更低。 - `"auto"` @@ -828,7 +828,7 @@ - `learning_rate_multiplier: optional "auto" or number` - 学习率的缩放因子。较小的学习率可能有助于避免过拟合。 + 学习率的缩放因子。使用较小的学习率可能有助于避免过拟合。 - `"auto"` @@ -838,7 +838,7 @@ - `n_epochs: optional "auto" or number` - 训练模型的轮数。一轮是指对训练数据集进行的一次完整循环。 + 训练模型的轮次数。一个 epoch 指的是对训练数据集进行一次完整的遍历。 - `"auto"` diff --git a/docs/zh/api/reference/resources/graders.md b/docs/zh/api/reference/resources/graders.md index a7e4a11..21526ca 100644 --- a/docs/zh/api/reference/resources/graders.md +++ b/docs/zh/api/reference/resources/graders.md @@ -1,6 +1,6 @@ -# 评分器 +# Graders -> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt). 可通过在页面 URL 后追加 `.md` 来获取文档页面的 Markdown 版本。 # 评分模型 @@ -10,20 +10,20 @@ - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入项列表，每个输入项可以是输入文本、输出文本、输入 + 一个输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `text: string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `type: "input_text"` @@ -33,7 +33,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结尾。断点继承自请求的 `prompt_cache_options.ttl`；该边界不四舍五入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会向上取整到 token 块。 - `mode: "explicit"` @@ -57,7 +57,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -71,11 +71,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `input_audio: object { data, format }` @@ -98,30 +98,30 @@ - `"input_audio"` -### 标签模型评分器 +### Label Model Grader - `LabelModelGrader object { input, labels, model, 3 more }` - 一个 LabelModelGrader 对象，使用模型为每个项目分配标签 - 在评估中。 + 一个 LabelModelGrader 对象，使用模型为评估中的每个项目分配标签 + 。 - `input: array of object { content, role, type }` - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，既可以是单个项目，也可以是项目数组。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `text: string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `type: "input_text"` @@ -131,7 +131,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结尾。断点继承自请求的 `prompt_cache_options.ttl`；该边界不四舍五入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会向上取整到 token 块。 - `mode: "explicit"` @@ -155,7 +155,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -169,11 +169,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `input_audio: object { data, format }` @@ -198,16 +198,16 @@ - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入项列表，每个输入项可以是输入文本、输出文本、输入 + 一个输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -225,7 +225,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -239,11 +239,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `role: "user" or "assistant" or "system" or "developer"` @@ -278,7 +278,7 @@ - `passing_labels: array of string` - 表示通过结果的标签。必须是标签的子集。 + 表示通过结果的标签。必须是 labels 的子集。 - `type: "label_model"` @@ -286,11 +286,11 @@ - `"label_model"` -### 多评分器 +### Multi Grader - `MultiGrader object { calculate_output, graders, name, type }` - MultiGrader 对象结合多个评分器的输出来生成单一评分。 + MultiGrader 对象将多个评分器的输出合并为单个分数。 - `calculate_output: string` @@ -298,11 +298,11 @@ - `graders: StringCheckGrader or TextSimilarityGrader or PythonGrader or 2 more` - StringCheckGrader 对象，使用指定操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作在输入和参考之间执行字符串比较。 - `StringCheckGrader object { input, name, operation, 2 more }` - StringCheckGrader 对象，使用指定操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作在输入和参考之间执行字符串比较。 - `input: string` @@ -314,7 +314,7 @@ - `operation: "eq" or "ne" or "like" or "ilike"` - 要执行的字符串检查操作。其中之一： `eq`, `ne`, `like`，或 `ilike`. + 要执行的字符串检查操作。可选值之一为 `eq`, `ne`, `like`，或 `ilike`. - `"eq"` @@ -336,11 +336,11 @@ - `TextSimilarityGrader object { evaluation_metric, input, name, 2 more }` - TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 + 一个 TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 - `evaluation_metric: "cosine" or "fuzzy_match" or "bleu" or 8 more` - 要使用的评估指标。其中之一： `cosine`, `fuzzy_match`, `bleu`, + 要使用的评估指标。可选值之一为 `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, 或 `rouge_l`. @@ -376,7 +376,7 @@ - `reference: string` - 用于评分的对照文本。 + 用于对比评分的文本。 - `type: "text_similarity"` @@ -386,7 +386,7 @@ - `PythonGrader object { name, source, type, image_tag }` - PythonGrader 对象，在输入上运行 Python 脚本。 + 一个 PythonGrader 对象，在输入上运行 Python 脚本。 - `name: string` @@ -404,11 +404,11 @@ - `image_tag: optional string` - 用于 Python 脚本的镜像标签。 + Python 脚本使用的镜像标签。 - `ScoreModelGrader object { input, model, name, 3 more }` - ScoreModelGrader 对象，使用模型为输入分配评分。 + 一个 ScoreModelGrader 对象，使用模型为输入打分。 - `input: array of object { content, role, type }` @@ -416,19 +416,19 @@ - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，既可以是单个项目，也可以是项目数组。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `text: string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `type: "input_text"` @@ -438,7 +438,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结尾。断点继承自请求的 `prompt_cache_options.ttl`；该边界不四舍五入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会向上取整到 token 块。 - `mode: "explicit"` @@ -462,7 +462,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -476,11 +476,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `input_audio: object { data, format }` @@ -505,16 +505,16 @@ - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入项列表，每个输入项可以是输入文本、输出文本、输入 + 一个输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -532,7 +532,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -546,11 +546,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `role: "user" or "assistant" or "system" or "developer"` @@ -587,7 +587,7 @@ - `range: optional array of number` - 评分的范围。默认为 `[0, 1]`. + 分数的范围。默认为 `[0, 1]`. - `sampling_params: optional object { max_completions_tokens, reasoning_effort, seed, 2 more }` @@ -599,13 +599,13 @@ - `reasoning_effort: optional ReasoningEffort or null` - 限制推理模型在推理上的投入。目前支持的 - 值有 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. - 降低推理投入可以加快响应速度并减少 token - 在响应中的使用量。并非所有推理模型都支持每个 - 值。参见 + 限制推理模型在推理上的投入程度。当前支持的 + 取值为 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. + 降低推理投入可以带来更快的响应，并减少响应中用于推理的 token 数量。并非所有推理模型都 + 支持每个取值。有关特定模型的支持情况，请参阅 + 推理指南 [推理指南](https://platform.openai.com/docs/guides/reasoning) - 了解模型特定的支持情况。 + 。 - `"none"` @@ -623,34 +623,34 @@ - `seed: optional number or null` - 在采样期间用于初始化随机性的种子值。 + 在采样过程中用于初始化随机性的种子值。 - `temperature: optional number or null` - 较高的温度会增加输出的随机性。 + 较高的温度会增大输出中的随机性。 - `top_p: optional number or null` - 温度在核心采样中的替代方案；1.0 包含所有 token。 + 用于核采样的温度替代方案；1.0 包含所有 token。 - `LabelModelGrader object { input, labels, model, 3 more }` - 一个 LabelModelGrader 对象，使用模型为每个项目分配标签 - 在评估中。 + 一个 LabelModelGrader 对象，使用模型为评估中的每个项目分配标签 + 。 - `input: array of object { content, role, type }` - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，既可以是单个项目，也可以是项目数组。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -668,7 +668,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -682,15 +682,15 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入项列表，每个输入项可以是输入文本、输出文本、输入 + 一个输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `role: "user" or "assistant" or "system" or "developer"` @@ -726,7 +726,7 @@ - `passing_labels: array of string` - 表示通过结果的标签。必须是标签的子集。 + 表示通过结果的标签。必须是 labels 的子集。 - `type: "label_model"` @@ -748,7 +748,7 @@ - `PythonGrader object { name, source, type, image_tag }` - PythonGrader 对象，在输入上运行 Python 脚本。 + 一个 PythonGrader 对象，在输入上运行 Python 脚本。 - `name: string` @@ -766,13 +766,13 @@ - `image_tag: optional string` - 用于 Python 脚本的镜像标签。 + Python 脚本使用的镜像标签。 -### 分数模型评分器 +### 模型评分评分器 - `ScoreModelGrader object { input, model, name, 3 more }` - ScoreModelGrader 对象，使用模型为输入分配评分。 + 一个 ScoreModelGrader 对象，使用模型为输入打分。 - `input: array of object { content, role, type }` @@ -780,19 +780,19 @@ - `content: string or ResponseInputText or object { text, type } or 3 more` - 模型的输入 - 可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，可以是单个项目或项目数组。 + 模型的输入——可以包含模板字符串。支持文本、输出文本、输入图像和输入音频，既可以是单个项目，也可以是项目数组。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `text: string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `type: "input_text"` @@ -802,7 +802,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的精确结尾。断点继承自请求的 `prompt_cache_options.ttl`；该边界不四舍五入到令牌块。 + 标记可复用提示前缀的精确结束位置。该断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会向上取整到 token 块。 - `mode: "explicit"` @@ -826,7 +826,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -840,11 +840,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `input_audio: object { data, format }` @@ -869,16 +869,16 @@ - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more` - 输入项列表，每个输入项可以是输入文本、输出文本、输入 + 一个输入列表，其中每个输入可以是输入文本、输出文本、输入 图像或输入音频对象。 - `TextInput = string` - 输入给模型的文本。 + 提供给模型的文本输入。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 输入给模型的文本。 + 提供给模型的文本输入。 - `OutputText object { text, type }` @@ -896,7 +896,7 @@ - `InputImage object { image_url, type, detail }` - 用于 EvalItem 内容数组中的图像输入块。 + 在 EvalItem 内容数组中使用的图像输入块。 - `image_url: string` @@ -910,11 +910,11 @@ - `detail: optional string` - 发送给模型的图像的细节级别。可为 `high`, `low`，或 `auto`。默认为 `auto`. + 发送给模型的图像细节级别。取值之一为 `high`, `low`，或 `auto`。默认为 `auto`. - `ResponseInputAudio object { input_audio, type }` - 输入给模型的音频。 + 提供给模型的音频输入。 - `role: "user" or "assistant" or "system" or "developer"` @@ -951,7 +951,7 @@ - `range: optional array of number` - 评分的范围。默认为 `[0, 1]`. + 分数的范围。默认为 `[0, 1]`. - `sampling_params: optional object { max_completions_tokens, reasoning_effort, seed, 2 more }` @@ -963,13 +963,13 @@ - `reasoning_effort: optional ReasoningEffort or null` - 限制推理模型在推理上的投入。目前支持的 - 值有 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. - 降低推理投入可以加快响应速度并减少 token - 在响应中的使用量。并非所有推理模型都支持每个 - 值。参见 + 限制推理模型在推理上的投入程度。当前支持的 + 取值为 `none`, `minimal`, `low`, `medium`, `high`, `xhigh`，以及 `max`. + 降低推理投入可以带来更快的响应，并减少响应中用于推理的 token 数量。并非所有推理模型都 + 支持每个取值。有关特定模型的支持情况，请参阅 + 推理指南 [推理指南](https://platform.openai.com/docs/guides/reasoning) - 了解模型特定的支持情况。 + 。 - `"none"` @@ -987,21 +987,21 @@ - `seed: optional number or null` - 在采样期间用于初始化随机性的种子值。 + 在采样过程中用于初始化随机性的种子值。 - `temperature: optional number or null` - 较高的温度会增加输出的随机性。 + 较高的温度会增大输出中的随机性。 - `top_p: optional number or null` - 温度在核心采样中的替代方案；1.0 包含所有 token。 + 用于核采样的温度替代方案；1.0 包含所有 token。 ### 字符串检查评分器 - `StringCheckGrader object { input, name, operation, 2 more }` - StringCheckGrader 对象，使用指定操作对输入和参考进行字符串比较。 + 一个 StringCheckGrader 对象，使用指定的操作在输入和参考之间执行字符串比较。 - `input: string` @@ -1013,7 +1013,7 @@ - `operation: "eq" or "ne" or "like" or "ilike"` - 要执行的字符串检查操作。其中之一： `eq`, `ne`, `like`，或 `ilike`. + 要执行的字符串检查操作。可选值之一为 `eq`, `ne`, `like`，或 `ilike`. - `"eq"` @@ -1037,11 +1037,11 @@ - `TextSimilarityGrader object { evaluation_metric, input, name, 2 more }` - TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 + 一个 TextSimilarityGrader 对象，根据相似度指标对文本进行评分。 - `evaluation_metric: "cosine" or "fuzzy_match" or "bleu" or 8 more` - 要使用的评估指标。其中之一： `cosine`, `fuzzy_match`, `bleu`, + 要使用的评估指标。可选值之一为 `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, 或 `rouge_l`. @@ -1077,7 +1077,7 @@ - `reference: string` - 用于评分的对照文本。 + 用于对比评分的文本。 - `type: "text_similarity"` diff --git a/docs/zh/api/reference/resources/images.md b/docs/zh/api/reference/resources/images.md index 49d82bf..9702452 100644 --- a/docs/zh/api/reference/resources/images.md +++ b/docs/zh/api/reference/resources/images.md @@ -1,14 +1,14 @@ -# 图像 +# 图片 -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 完整文档索引请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 末尾追加 `.md` 来获取 Markdown 格式的文档页面。 -## 创建图像变体 +## 创建图片变体 **post** `/images/variations` -创建给定图像的变体。此端点仅支持 `dall-e-2`. +根据给定图像生成变体。该端点仅支持 `dall-e-2`. -### 返回 +### Returns - `ImagesResponse object { created, background, data, 4 more }` @@ -16,11 +16,11 @@ - `created: number` - 创建图像时的 Unix 时间戳（秒）。 + 图像创建时的 Unix 时间戳（以秒为单位）。 - `background: optional "transparent" or "opaque"` - 图像生成中使用的背景参数。可为 `transparent` 或 `opaque`. + 用于图像生成的 background 参数。可以是 `transparent` 或 `opaque`. - `"transparent"` @@ -32,19 +32,19 @@ - `b64_json: optional string` - 生成图像的 base64 编码 JSON。对于 GPT 图像模型默认返回，且仅在 `response_format` 设置为 `b64_json` 时，对 `dall-e-2` 和 `dall-e-3`. + 生成图像的 base64 编码 JSON。默认由 GPT image 模型返回，并且仅在 `response_format` 设置为 `b64_json` 时 `dall-e-2` 且 `dall-e-3`. - `revised_prompt: optional string` - 对于 `dall-e-3` ，仅提供用于生成图像的修订提示词。 + 为 `dall-e-3` 时才存在，用于生成图像的修订后提示词。 - `url: optional string` - 当使用 `dall-e-2` 或 `dall-e-3`，时，生成的图像 URL，如果 `response_format` 设置为 `url` （默认值）。GPT 图像模型不支持。 + 当使用 `dall-e-2` 或 `dall-e-3`，时，如果 `response_format` 设置为 `url` （默认值）则为生成图像的 URL。不受 GPT image 模型支持。 - `output_format: optional "png" or "webp" or "jpeg"` - 图像生成的输出格式。可为 `png`, `webp`，或 `jpeg`. + 图像生成的输出格式。可以是 `png`, `webp`，或 `jpeg`. - `"png"` @@ -54,7 +54,7 @@ - `quality: optional "low" or "medium" or "high"` - 生成图像的质量。可为 `low`, `medium`，或 `high`. + 生成图像的质量。可以是 `low`, `medium`，或 `high`. - `"low"` @@ -64,7 +64,7 @@ - `size: optional "1024x1024" or "1024x1536" or "1536x1024"` - 生成图像的大小。可为 `1024x1024`, `1024x1536`，或 `1536x1024`. + 生成图像的尺寸。可以是 `1024x1024`, `1024x1536`，或 `1536x1024`. - `"1024x1024"` @@ -74,43 +74,43 @@ - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - 对于 `gpt-image-1` ，仅提供图像生成的令牌使用信息。 + 为 `gpt-image-1` 时，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 模型生成的输出令牌数量。 + 模型生成的输出 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 - `output_tokens_details: optional object { image_tokens, text_tokens }` - 图像生成的输出令牌详细信息。 + 图像生成的输出 token 详细信息。 - `image_tokens: number` - 模型生成的图像输出令牌数量。 + 模型生成的图像输出 token 数量。 - `text_tokens: number` - 模型生成的文本输出令牌数量。 + 模型生成的文本输出 token 数量。 ### 示例 @@ -183,34 +183,34 @@ curl https://api.openai.com/v1/images/variations \ } ``` -## 创建图像编辑 +## 创建图片编辑 **post** `/images/edits` -根据一个或多个源图像和提示词创建编辑或扩展后的图像。此端点支持 GPT Image 模型（`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`，以及 `chatgpt-image-latest`) 和 `dall-e-2`. +根据一个或多个源图像和提示创建编辑版或扩展版图像。该端点支持 GPT Image 模型（`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`，以及 `chatgpt-image-latest`）。 `dall-e-2`. ### 请求体参数 - `images: array of object { file_id, image_url }` - 要编辑的输入图片引用。 - 对于 GPT 图像模型，你可以提供最多 16 张图片。 + 作为编辑输入的图像引用。 + 对于 GPT 图像模型，你可以提供最多 16 张图像。 - `file_id: optional string` - 作为输入的上传图片的 File API ID。 + 用作输入的上传图像的 File API ID。 - `image_url: optional string` - 完全限定的 URL 或 base64 编码的数据 URL。 + 一个完全限定的 URL 或 base64 编码的数据 URL。 - `prompt: string` - 期望图像编辑的文本描述。 + 对所需图像编辑的文字描述。 - `background: optional "transparent" or "opaque" or "auto" or null` - 设置生成图像输出的背景。对于支持的 GPT 图像模型，可以使用透明背景。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，此支持处于预览阶段。使用 `transparent`，时，请将输出格式设置为 `png` 或 `webp`. + 设置生成图像输出的背景。受支持的 GPT Image 模型可使用透明背景。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，该支持处于预览阶段。使用 `transparent`，时，将输出格式设置为 `png` 或 `webp`. - `"transparent"` @@ -229,25 +229,25 @@ curl https://api.openai.com/v1/images/variations \ - `mask: optional object { file_id, image_url }` 通过 URL 或上传的文件 ID 引用输入图像。 - 仅提供以下之一 `image_url` 或 `file_id`. + 提供以下之一： `image_url` 或 `file_id`. - `file_id: optional string` - 作为输入的上传图片的 File API ID。 + 用作输入的上传图像的 File API ID。 - `image_url: optional string` - 完全限定的 URL 或 base64 编码的数据 URL。 + 一个完全限定的 URL 或 base64 编码的数据 URL。 - `model: optional string or "gpt-image-1.5" or "gpt-image-2" or "gpt-image-2-2026-04-21" or 3 more or null` - 用于图像编辑的 GPT 图像模型，包括 `gpt-image-2` 及其带日期的快照 `gpt-image-2-2026-04-21`. + 用于图像编辑的 GPT 图像模型，包括 `gpt-image-2` 及其对应的日期快照 `gpt-image-2-2026-04-21`. - `string` - `"gpt-image-1.5" or "gpt-image-2" or "gpt-image-2-2026-04-21" or 3 more` - 用于图像编辑的 GPT 图像模型，包括 `gpt-image-2` 及其带日期的快照 `gpt-image-2-2026-04-21`. + 用于图像编辑的 GPT 图像模型，包括 `gpt-image-2` 及其对应的日期快照 `gpt-image-2-2026-04-21`. - `"gpt-image-1.5"` @@ -263,7 +263,7 @@ curl https://api.openai.com/v1/images/variations \ - `moderation: optional "low" or "auto" or null` - GPT 图像模型的审核级别。 + GPT 图像模型的内容审核级别。 - `"low"` @@ -275,11 +275,11 @@ curl https://api.openai.com/v1/images/variations \ - `output_compression: optional number or null` - 压缩级别 `jpeg` 或 `webp` 输出。 + 的压缩级别 `jpeg` 或 `webp` 输出。 - `output_format: optional "png" or "jpeg" or "webp" or null` - 输出图像格式。支持 GPT 图像模型。 + 输出图像格式。GPT 图像模型支持。 - `"png"` @@ -289,12 +289,12 @@ curl https://api.openai.com/v1/images/variations \ - `partial_images: optional number or null` - 要生成的部分图像数量。此参数用于 - 返回部分图像的流式响应。值必须在 0 到 3 之间。 - 当设为 0 时，响应将是一张在单个流式事件中发送的图片。 + 要生成的中间图像数量。此参数用于 + 返回中间图像的流式响应。值必须介于 0 到 3 之间。 + 当设置为 0 时，响应将作为单个图像在一次流式事件中发送。 - 请注意，如果完整图片生成得更快，最终图片可能会在全部部分图片 - 生成之前发送。 + 注意，如果完整图像生成得更快，最终图像可能会在生成完所有部分图像之前发送 + 。 - `quality: optional "low" or "medium" or "high" or "auto" or null` @@ -322,14 +322,14 @@ curl https://api.openai.com/v1/images/variations \ - `stream: optional boolean or null` - 以事件形式流式传输部分图像结果。 + 将部分图像结果作为事件进行流式传输。 - `user: optional string` - 代表最终用户的唯一标识符，这可以帮助 OpenAI + 代表你终端用户的唯一标识符，可帮助 OpenAI 监控并检测滥用行为。 -### 返回 +### Returns - `ImagesResponse object { created, background, data, 4 more }` @@ -337,11 +337,11 @@ curl https://api.openai.com/v1/images/variations \ - `created: number` - 创建图像时的 Unix 时间戳（秒）。 + 图像创建时的 Unix 时间戳（以秒为单位）。 - `background: optional "transparent" or "opaque"` - 图像生成中使用的背景参数。可为 `transparent` 或 `opaque`. + 用于图像生成的 background 参数。可以是 `transparent` 或 `opaque`. - `"transparent"` @@ -353,19 +353,19 @@ curl https://api.openai.com/v1/images/variations \ - `b64_json: optional string` - 生成图像的 base64 编码 JSON。对于 GPT 图像模型默认返回，且仅在 `response_format` 设置为 `b64_json` 时，对 `dall-e-2` 和 `dall-e-3`. + 生成图像的 base64 编码 JSON。默认由 GPT image 模型返回，并且仅在 `response_format` 设置为 `b64_json` 时 `dall-e-2` 且 `dall-e-3`. - `revised_prompt: optional string` - 对于 `dall-e-3` ，仅提供用于生成图像的修订提示词。 + 为 `dall-e-3` 时才存在，用于生成图像的修订后提示词。 - `url: optional string` - 当使用 `dall-e-2` 或 `dall-e-3`，时，生成的图像 URL，如果 `response_format` 设置为 `url` （默认值）。GPT 图像模型不支持。 + 当使用 `dall-e-2` 或 `dall-e-3`，时，如果 `response_format` 设置为 `url` （默认值）则为生成图像的 URL。不受 GPT image 模型支持。 - `output_format: optional "png" or "webp" or "jpeg"` - 图像生成的输出格式。可为 `png`, `webp`，或 `jpeg`. + 图像生成的输出格式。可以是 `png`, `webp`，或 `jpeg`. - `"png"` @@ -375,7 +375,7 @@ curl https://api.openai.com/v1/images/variations \ - `quality: optional "low" or "medium" or "high"` - 生成图像的质量。可为 `low`, `medium`，或 `high`. + 生成图像的质量。可以是 `low`, `medium`，或 `high`. - `"low"` @@ -385,7 +385,7 @@ curl https://api.openai.com/v1/images/variations \ - `size: optional "1024x1024" or "1024x1536" or "1536x1024"` - 生成图像的大小。可为 `1024x1024`, `1024x1536`，或 `1536x1024`. + 生成图像的尺寸。可以是 `1024x1024`, `1024x1536`，或 `1536x1024`. - `"1024x1024"` @@ -395,43 +395,43 @@ curl https://api.openai.com/v1/images/variations \ - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - 对于 `gpt-image-1` ，仅提供图像生成的令牌使用信息。 + 为 `gpt-image-1` 时，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 模型生成的输出令牌数量。 + 模型生成的输出 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 - `output_tokens_details: optional object { image_tokens, text_tokens }` - 图像生成的输出令牌详细信息。 + 图像生成的输出 token 详细信息。 - `image_tokens: number` - 模型生成的图像输出令牌数量。 + 模型生成的图像输出 token 数量。 - `text_tokens: number` - 模型生成的文本输出令牌数量。 + 模型生成的文本输出 token 数量。 ### 示例 @@ -499,7 +499,7 @@ curl -s -D >(grep -i x-request-id >&2) \ -F 'prompt=Create a lovely gift basket with these four items in it' ``` -### 流式输出 +### 流式传输 ```http curl -s -N -X POST "https://api.openai.com/v1/images/edits" \ @@ -527,24 +527,24 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 **post** `/images/generations` -根据提示词创建图像。 [了解更多](/docs/guides/images). +根据提示词创建一张图像。 [了解更多](/docs/guides/images). ### 请求体参数 - `prompt: string` - 所需图像的文本描述。对于 GPT 图像模型，最大长度为 32000 个字符；对于 `dall-e-2` 为 1000 个字符，对于 `dall-e-3`. + 所需图像的文字描述。GPT 图像模型的最大长度为 32000 个字符， `dall-e-2` 为 1000 个字符， `dall-e-3`. - `background: optional "transparent" or "opaque" or "auto" or null` - 为 4000 个字符。设置生成图像的背景。此参数仅 - 受 GPT 图像模型支持。必须是以下之一： `transparent`, `opaque`, + 设置生成图像的背景。此参数仅 + GPT 图像模型支持。必须是以下之一 `transparent`, `opaque`, 或 `auto` （默认值）。当使用 `auto` 时，模型将自动 - 确定图像的最佳背景。 + 为图像确定最佳背景。 - 对于支持的 GPT 图像模型，透明背景可用。对于 - `gpt-image-2` 和 `gpt-image-2-2026-04-21`，此支持处于预览阶段。当使用 - 时 `transparent`，时，请将输出格式设置为 `png` 或 `webp`. + 受支持的 GPT 图像模型可使用透明背景。对于 + `gpt-image-2` 且 `gpt-image-2-2026-04-21`，此功能处于预览阶段。使用 + 时 `transparent`，时，将输出格式设置为 `png` 或 `webp`. - `"transparent"` @@ -554,7 +554,7 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `model: optional string or ImageModel or null` - 用于图像生成的模型。可以是以下之一： `dall-e-2`, `dall-e-3`，或 GPT 图像模型（`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`）。默认值为 `dall-e-2` ，除非使用了 GPT 图像模型特有的参数。 + 用于图像生成的模型。以下之一 `dall-e-2`, `dall-e-3`，或 GPT 图像模型（`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`）。默认为 `dall-e-2` ，除非使用了 GPT 图像模型特有的参数。 - `string` @@ -576,7 +576,7 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `moderation: optional "low" or "auto" or null` - 控制 GPT 图像模型生成图像的内容审核级别。必须是以下之一： `low` 以实现较宽松的过滤，或 `auto` （默认值）。 + 控制 GPT 图像模型生成图像的内容审核级别。必须是 `low` （限制较低的过滤）或 `auto` （默认值）之一。 - `"low"` @@ -584,15 +584,15 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `n: optional number or null` - 要生成的图像数量。必须介于 1 和 10 之间。对于 `dall-e-3`，仅支持 `n=1` 。 + 要生成的图像数量。必须在 1 到 10 之间。对于 `dall-e-3`，仅支持 `n=1` 。 - `output_compression: optional number or null` - 生成图像的压缩级别（0-100%）。此参数仅受支持 GPT 图像模型的 `webp` 或 `jpeg` 输出格式支持，默认值为 100。 + 生成图像的压缩级别（0-100%）。此参数仅在使用 `webp` 或 `jpeg` 输出格式时受支持，默认为 100。 - `output_format: optional "png" or "jpeg" or "webp" or null` - 生成图像的返回格式。此参数仅受 GPT 图像模型支持。必须为以下之一 `png`, `jpeg`，或 `webp`. + 生成图像的返回格式。此参数仅受 GPT 图像模型支持。必须是以下值之一 `png`, `jpeg`，或 `webp`. - `"png"` @@ -602,21 +602,21 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `partial_images: optional number or null` - 要生成的部分图像数量。此参数用于 - 返回部分图像的流式响应。值必须在 0 到 3 之间。 - 当设为 0 时，响应将是一张在单个流式事件中发送的图片。 + 要生成的中间图像数量。此参数用于 + 返回中间图像的流式响应。值必须介于 0 到 3 之间。 + 当设置为 0 时，响应将作为单个图像在一次流式事件中发送。 - 请注意，如果完整图片生成得更快，最终图片可能会在全部部分图片 - 生成之前发送。 + 注意，如果完整图像生成得更快，最终图像可能会在生成完所有部分图像之前发送 + 。 - `quality: optional "standard" or "hd" or "low" or 3 more or null` - 将要生成的图像的质量。 + 生成图像的质量。 - `auto` （默认值）将自动为给定模型选择最佳质量。 - - `high`, `medium` 和 `low` 受 GPT 图像模型支持。 - - `hd` 和 `standard` 支持 `dall-e-3`. - - `standard` 是唯一选项 `dall-e-2`. + - `high`, `medium` 且 `low` 受 GPT 图像模型支持。 + - `hd` 且 `standard` 受以下模型支持： `dall-e-3`. + - `standard` 是以下模型的唯一选项： `dall-e-2`. - `"standard"` @@ -632,7 +632,7 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `response_format: optional "url" or "b64_json" or null` - 生成图像的格式，其中 `dall-e-2` 和 `dall-e-3` 被返回。必须为以下之一 `url` 或 `b64_json`。URL 在图像生成后仅 60 分钟内有效。此参数不受 GPT 图像模型支持，这些模型始终返回 base64 编码的图像。 + 使用以下格式时生成图像的返回格式： `dall-e-2` 且 `dall-e-3` 返回。必须是以下值之一： `url` 或 `b64_json`。URL 仅在图像生成后的 60 分钟内有效。此参数不受 GPT 图像模型支持，这些模型始终返回 base64 编码的图像。 - `"url"` @@ -640,13 +640,13 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `size: optional string or "auto" or "1024x1024" or "1536x1024" or 5 more or null` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须都能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。有关 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持以字符串形式指定任意分辨率，例如 `WIDTHxHEIGHT` 。宽度和高度必须都能被 16 整除，且所请求的长宽比必须介于 1:3 与 3:1 之间。高于 `1536x864`。的分辨率为实验性功能，最大支持的分辨率为 `2560x1440` 。所请求的尺寸也必须满足模型当前的像素和边长限制。标准尺寸 `3840x2160`。所请求的尺寸也必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`、 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下其中之一 `256x256`, `512x512`，或 `1024x1024`。有关 `dall-e-3`，请使用以下其中之一 `1024x1024`, `1792x1024`，或 `1024x1792`. - `string` - `"auto" or "1024x1024" or "1536x1024" or 5 more` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度必须都能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`，以及 `1024x1536` 受 GPT 图像模型支持； `auto` 支持允许自动调整大小的模型。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。有关 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 且 `gpt-image-2-2026-04-21`，支持以字符串形式指定任意分辨率，例如 `WIDTHxHEIGHT` 。宽度和高度必须都能被 16 整除，且所请求的长宽比必须介于 1:3 与 3:1 之间。高于 `1536x864`。的分辨率为实验性功能，最大支持的分辨率为 `2560x1440` 。所请求的尺寸也必须满足模型当前的像素和边长限制。标准尺寸 `3840x2160`。所请求的尺寸也必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`、 `1024x1536` 受 GPT 图像模型支持； `auto` 受支持用于允许自动调整尺寸的模型。对于 `dall-e-2`，请使用以下其中之一 `256x256`, `512x512`，或 `1024x1024`。有关 `dall-e-3`，请使用以下其中之一 `1024x1024`, `1792x1024`，或 `1024x1792`. - `"auto"` @@ -666,13 +666,13 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `stream: optional boolean or null` - 以流式模式生成图像。默认为 `false`。有关更多信息，请参阅 - [图像生成指南](/docs/guides/image-generation) 。 - 此参数仅受 GPT 图像模型支持。 + 以流式模式生成图像。默认为 `false`。请参阅 + [图像生成指南](/docs/guides/image-generation) 了解更多信息。 + 此参数仅在 GPT 图像模型中受支持。 - `style: optional "vivid" or "natural" or null` - 生成图像的风格。此参数仅受 `dall-e-3`。支持。必须为以下之一 `vivid` 或 `natural`。Vivid 使模型倾向于生成超现实和戏剧性的图像。Natural 使模型生成更自然、不那么超现实的图像。 + 所生成图像的风格。此参数仅在 `dall-e-3`。中受支持。必须为以下值之一 `vivid` 或 `natural`。Vivid 会使模型倾向于生成超现实、富有戏剧性的图像。Natural 会使模型生成更自然、不那么超现实的图像。 - `"vivid"` @@ -680,9 +680,9 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `user: optional string` - 代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。 [了解更多](/docs/guides/safety-best-practices#end-user-ids). + 用于代表终端用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。 [了解更多](/docs/guides/safety-best-practices#end-user-ids). -### 返回 +### Returns - `ImagesResponse object { created, background, data, 4 more }` @@ -690,11 +690,11 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `created: number` - 创建图像时的 Unix 时间戳（秒）。 + 图像创建时的 Unix 时间戳（以秒为单位）。 - `background: optional "transparent" or "opaque"` - 图像生成中使用的背景参数。可为 `transparent` 或 `opaque`. + 用于图像生成的 background 参数。可以是 `transparent` 或 `opaque`. - `"transparent"` @@ -706,19 +706,19 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `b64_json: optional string` - 生成图像的 base64 编码 JSON。对于 GPT 图像模型默认返回，且仅在 `response_format` 设置为 `b64_json` 时，对 `dall-e-2` 和 `dall-e-3`. + 生成图像的 base64 编码 JSON。默认由 GPT image 模型返回，并且仅在 `response_format` 设置为 `b64_json` 时 `dall-e-2` 且 `dall-e-3`. - `revised_prompt: optional string` - 对于 `dall-e-3` ，仅提供用于生成图像的修订提示词。 + 为 `dall-e-3` 时才存在，用于生成图像的修订后提示词。 - `url: optional string` - 当使用 `dall-e-2` 或 `dall-e-3`，时，生成的图像 URL，如果 `response_format` 设置为 `url` （默认值）。GPT 图像模型不支持。 + 当使用 `dall-e-2` 或 `dall-e-3`，时，如果 `response_format` 设置为 `url` （默认值）则为生成图像的 URL。不受 GPT image 模型支持。 - `output_format: optional "png" or "webp" or "jpeg"` - 图像生成的输出格式。可为 `png`, `webp`，或 `jpeg`. + 图像生成的输出格式。可以是 `png`, `webp`，或 `jpeg`. - `"png"` @@ -728,7 +728,7 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `quality: optional "low" or "medium" or "high"` - 生成图像的质量。可为 `low`, `medium`，或 `high`. + 生成图像的质量。可以是 `low`, `medium`，或 `high`. - `"low"` @@ -738,7 +738,7 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"` - 生成图像的大小。可为 `1024x1024`, `1024x1536`，或 `1536x1024`. + 生成图像的尺寸。可以是 `1024x1024`, `1024x1536`，或 `1536x1024`. - `"1024x1024"` @@ -748,43 +748,43 @@ data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":10 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - 对于 `gpt-image-1` ，仅提供图像生成的令牌使用信息。 + 为 `gpt-image-1` 时，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 模型生成的输出令牌数量。 + 模型生成的输出 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 - `output_tokens_details: optional object { image_tokens, text_tokens }` - 图像生成的输出令牌详细信息。 + 图像生成的输出 token 详细信息。 - `image_tokens: number` - 模型生成的图像输出令牌数量。 + 模型生成的图像输出 token 数量。 - `text_tokens: number` - 模型生成的文本输出令牌数量。 + 模型生成的文本输出 token 数量。 ### 示例 @@ -839,7 +839,7 @@ curl https://api.openai.com/v1/images/generations \ } ``` -### 生成图像 +### 生成图片 ```http curl https://api.openai.com/v1/images/generations \ @@ -875,7 +875,7 @@ curl https://api.openai.com/v1/images/generations \ } ``` -### 流式输出 +### 流式传输 ```http curl https://api.openai.com/v1/images/generations \ @@ -901,39 +901,39 @@ event: image_generation.completed data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}} ``` -## 域类型 +## 域名类型 -### 图像 +### Image - `Image object { b64_json, revised_prompt, url }` - 表示由OpenAI API生成的图像的内容或URL。 + 表示由 OpenAI API 生成的图像的内容或 URL。 - `b64_json: optional string` - 生成图像的 base64 编码 JSON。对于 GPT 图像模型默认返回，且仅在 `response_format` 设置为 `b64_json` 时，对 `dall-e-2` 和 `dall-e-3`. + 生成图像的 base64 编码 JSON。默认由 GPT image 模型返回，并且仅在 `response_format` 设置为 `b64_json` 时 `dall-e-2` 且 `dall-e-3`. - `revised_prompt: optional string` - 对于 `dall-e-3` ，仅提供用于生成图像的修订提示词。 + 为 `dall-e-3` 时才存在，用于生成图像的修订后提示词。 - `url: optional string` - 当使用 `dall-e-2` 或 `dall-e-3`，时，生成的图像 URL，如果 `response_format` 设置为 `url` （默认值）。GPT 图像模型不支持。 + 当使用 `dall-e-2` 或 `dall-e-3`，时，如果 `response_format` 设置为 `url` （默认值）则为生成图像的 URL。不受 GPT image 模型支持。 ### 图像编辑完成事件 - `ImageEditCompletedEvent object { b64_json, background, created_at, 5 more }` - 当图像编辑完成且最终图像可用时触发。 + 在图像编辑完成且最终图像可用时发出。 - `b64_json: string` - Base64 编码的最终编辑图像数据，适合渲染为图像。 + Base64 编码的最终编辑图像数据，适合作为图像渲染。 - `background: "transparent" or "opaque" or "auto"` - 编辑图像的背景设置。 + 编辑后图像的背景设置。 - `"transparent"` @@ -947,7 +947,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `output_format: "png" or "webp" or "jpeg"` - 编辑图像的输出格式。 + 编辑后图像的输出格式。 - `"png"` @@ -957,7 +957,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `quality: "low" or "medium" or "high" or "auto"` - 编辑图像的质量设置。 + 编辑后图像的质量设置。 - `"low"` @@ -969,7 +969,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 编辑图像的尺寸。 + 编辑后图像的尺寸。 - `"1024x1024"` @@ -981,43 +981,43 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_edit.completed"` - 事件类型。始终 `image_edit.completed`. + 事件的类型。始终为 `image_edit.completed`. - `"image_edit.completed"` - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }` - 仅针对 GPT 图像模型，图像生成的令牌使用信息。 + 仅适用于 GPT 图像模型，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 输出图像中的图像令牌数量。 + 输出图像中的图像 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 -### 图像编辑部分图像事件 +### 图像编辑分帧图像事件 - `ImageEditPartialImageEvent object { b64_json, background, created_at, 5 more }` - 在图像编辑流式传输期间，当部分图像可用时发出。 + 在图像编辑流式传输过程中，当有部分图像可用时发出。 - `b64_json: string` @@ -1025,7 +1025,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `background: "transparent" or "opaque" or "auto"` - 请求的编辑图像的背景设置。 + 所请求编辑图像的背景设置。 - `"transparent"` @@ -1039,7 +1039,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `output_format: "png" or "webp" or "jpeg"` - 请求的编辑图像的输出格式。 + 所请求编辑图像的输出格式。 - `"png"` @@ -1049,11 +1049,11 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `partial_image_index: number` - 部分图像（流式传输）的0基索引。 + 部分图像的从 0 开始的索引（流式传输）。 - `quality: "low" or "medium" or "high" or "auto"` - 请求的编辑图像的质量设置。 + 所请求编辑图像的质量设置。 - `"low"` @@ -1065,7 +1065,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 请求的编辑图像的尺寸。 + 所请求编辑图像的尺寸。 - `"1024x1024"` @@ -1077,7 +1077,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_edit.partial_image"` - 事件类型。始终 `image_edit.partial_image`. + 事件的类型。始终为 `image_edit.partial_image`. - `"image_edit.partial_image"` @@ -1085,11 +1085,11 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `ImageEditStreamEvent = ImageEditPartialImageEvent or ImageEditCompletedEvent` - 在图像编辑流式传输期间，当部分图像可用时发出。 + 在图像编辑流式传输过程中，当有部分图像可用时发出。 - `ImageEditPartialImageEvent object { b64_json, background, created_at, 5 more }` - 在图像编辑流式传输期间，当部分图像可用时发出。 + 在图像编辑流式传输过程中，当有部分图像可用时发出。 - `b64_json: string` @@ -1097,7 +1097,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `background: "transparent" or "opaque" or "auto"` - 请求的编辑图像的背景设置。 + 所请求编辑图像的背景设置。 - `"transparent"` @@ -1111,7 +1111,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `output_format: "png" or "webp" or "jpeg"` - 请求的编辑图像的输出格式。 + 所请求编辑图像的输出格式。 - `"png"` @@ -1121,11 +1121,11 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `partial_image_index: number` - 部分图像（流式传输）的0基索引。 + 部分图像的从 0 开始的索引（流式传输）。 - `quality: "low" or "medium" or "high" or "auto"` - 请求的编辑图像的质量设置。 + 所请求编辑图像的质量设置。 - `"low"` @@ -1137,7 +1137,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 请求的编辑图像的尺寸。 + 所请求编辑图像的尺寸。 - `"1024x1024"` @@ -1149,21 +1149,21 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_edit.partial_image"` - 事件类型。始终 `image_edit.partial_image`. + 事件的类型。始终为 `image_edit.partial_image`. - `"image_edit.partial_image"` - `ImageEditCompletedEvent object { b64_json, background, created_at, 5 more }` - 当图像编辑完成且最终图像可用时触发。 + 在图像编辑完成且最终图像可用时发出。 - `b64_json: string` - Base64 编码的最终编辑图像数据，适合渲染为图像。 + Base64 编码的最终编辑图像数据，适合作为图像渲染。 - `background: "transparent" or "opaque" or "auto"` - 编辑图像的背景设置。 + 编辑后图像的背景设置。 - `"transparent"` @@ -1177,7 +1177,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `output_format: "png" or "webp" or "jpeg"` - 编辑图像的输出格式。 + 编辑后图像的输出格式。 - `"png"` @@ -1187,7 +1187,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `quality: "low" or "medium" or "high" or "auto"` - 编辑图像的质量设置。 + 编辑后图像的质量设置。 - `"low"` @@ -1199,7 +1199,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 编辑图像的尺寸。 + 编辑后图像的尺寸。 - `"1024x1024"` @@ -1211,43 +1211,43 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_edit.completed"` - 事件类型。始终 `image_edit.completed`. + 事件的类型。始终为 `image_edit.completed`. - `"image_edit.completed"` - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }` - 仅针对 GPT 图像模型，图像生成的令牌使用信息。 + 仅适用于 GPT 图像模型，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 输出图像中的图像令牌数量。 + 输出图像中的图像 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 ### 图像生成完成事件 - `ImageGenCompletedEvent object { b64_json, background, created_at, 5 more }` - 当图像生成完成且最终图像可用时发出。 + 在图像生成完成且最终图像可用时发出。 - `b64_json: string` @@ -1303,43 +1303,43 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_generation.completed"` - 事件类型。始终 `image_generation.completed`. + 事件的类型。始终为 `image_generation.completed`. - `"image_generation.completed"` - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }` - 仅针对 GPT 图像模型，图像生成的令牌使用信息。 + 仅适用于 GPT 图像模型，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 输出图像中的图像令牌数量。 + 输出图像中的图像 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 -### 图片生成部分图片事件 +### Image Gen Partial Image Event - `ImageGenPartialImageEvent object { b64_json, background, created_at, 5 more }` - 在图像生成流式传输期间，有部分图像可用时发出。 + 在图像生成流式传输期间，当有部分图像可用时触发。 - `b64_json: string` @@ -1371,7 +1371,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `partial_image_index: number` - 部分图像（流式传输）的0基索引。 + 部分图像的从 0 开始的索引（流式传输）。 - `quality: "low" or "medium" or "high" or "auto"` @@ -1399,7 +1399,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_generation.partial_image"` - 事件类型。始终 `image_generation.partial_image`. + 事件的类型。始终为 `image_generation.partial_image`. - `"image_generation.partial_image"` @@ -1407,11 +1407,11 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `ImageGenStreamEvent = ImageGenPartialImageEvent or ImageGenCompletedEvent` - 在图像生成流式传输期间，有部分图像可用时发出。 + 在图像生成流式传输期间，当有部分图像可用时触发。 - `ImageGenPartialImageEvent object { b64_json, background, created_at, 5 more }` - 在图像生成流式传输期间，有部分图像可用时发出。 + 在图像生成流式传输期间，当有部分图像可用时触发。 - `b64_json: string` @@ -1443,7 +1443,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `partial_image_index: number` - 部分图像（流式传输）的0基索引。 + 部分图像的从 0 开始的索引（流式传输）。 - `quality: "low" or "medium" or "high" or "auto"` @@ -1471,13 +1471,13 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_generation.partial_image"` - 事件类型。始终 `image_generation.partial_image`. + 事件的类型。始终为 `image_generation.partial_image`. - `"image_generation.partial_image"` - `ImageGenCompletedEvent object { b64_json, background, created_at, 5 more }` - 当图像生成完成且最终图像可用时发出。 + 在图像生成完成且最终图像可用时发出。 - `b64_json: string` @@ -1533,37 +1533,37 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `type: "image_generation.completed"` - 事件类型。始终 `image_generation.completed`. + 事件的类型。始终为 `image_generation.completed`. - `"image_generation.completed"` - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }` - 仅针对 GPT 图像模型，图像生成的令牌使用信息。 + 仅适用于 GPT 图像模型，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 输出图像中的图像令牌数量。 + 输出图像中的图像 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 ### 图像模型 @@ -1591,11 +1591,11 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `created: number` - 创建图像时的 Unix 时间戳（秒）。 + 图像创建时的 Unix 时间戳（以秒为单位）。 - `background: optional "transparent" or "opaque"` - 图像生成中使用的背景参数。可为 `transparent` 或 `opaque`. + 用于图像生成的 background 参数。可以是 `transparent` 或 `opaque`. - `"transparent"` @@ -1607,19 +1607,19 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `b64_json: optional string` - 生成图像的 base64 编码 JSON。对于 GPT 图像模型默认返回，且仅在 `response_format` 设置为 `b64_json` 时，对 `dall-e-2` 和 `dall-e-3`. + 生成图像的 base64 编码 JSON。默认由 GPT image 模型返回，并且仅在 `response_format` 设置为 `b64_json` 时 `dall-e-2` 且 `dall-e-3`. - `revised_prompt: optional string` - 对于 `dall-e-3` ，仅提供用于生成图像的修订提示词。 + 为 `dall-e-3` 时才存在，用于生成图像的修订后提示词。 - `url: optional string` - 当使用 `dall-e-2` 或 `dall-e-3`，时，生成的图像 URL，如果 `response_format` 设置为 `url` （默认值）。GPT 图像模型不支持。 + 当使用 `dall-e-2` 或 `dall-e-3`，时，如果 `response_format` 设置为 `url` （默认值）则为生成图像的 URL。不受 GPT image 模型支持。 - `output_format: optional "png" or "webp" or "jpeg"` - 图像生成的输出格式。可为 `png`, `webp`，或 `jpeg`. + 图像生成的输出格式。可以是 `png`, `webp`，或 `jpeg`. - `"png"` @@ -1629,7 +1629,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `quality: optional "low" or "medium" or "high"` - 生成图像的质量。可为 `low`, `medium`，或 `high`. + 生成图像的质量。可以是 `low`, `medium`，或 `high`. - `"low"` @@ -1639,7 +1639,7 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `size: optional "1024x1024" or "1024x1536" or "1536x1024"` - 生成图像的大小。可为 `1024x1024`, `1024x1536`，或 `1536x1024`. + 生成图像的尺寸。可以是 `1024x1024`, `1024x1536`，或 `1536x1024`. - `"1024x1024"` @@ -1649,40 +1649,40 @@ data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_toke - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - 对于 `gpt-image-1` ，仅提供图像生成的令牌使用信息。 + 为 `gpt-image-1` 时，图像生成的 token 用量信息。 - `input_tokens: number` - 输入提示中的令牌数量（图像和文本）。 + 输入提示中的 token（图像和文本）数量。 - `input_tokens_details: object { image_tokens, text_tokens }` - 图像生成的输入令牌详细信息。 + 图像生成的输入 token 详细信息。 - `image_tokens: number` - 输入提示中的图像令牌数量。 + 输入提示中的图像 token 数量。 - `text_tokens: number` - 输入提示中的文本令牌数量。 + 输入提示中的文本 token 数量。 - `output_tokens: number` - 模型生成的输出令牌数量。 + 模型生成的输出 token 数量。 - `total_tokens: number` - 用于图像生成的总令牌数（图像和文本）。 + 用于图像生成的 token（图像和文本）总数量。 - `output_tokens_details: optional object { image_tokens, text_tokens }` - 图像生成的输出令牌详细信息。 + 图像生成的输出 token 详细信息。 - `image_tokens: number` - 模型生成的图像输出令牌数量。 + 模型生成的图像输出 token 数量。 - `text_tokens: number` - 模型生成的文本输出令牌数量。 + 模型生成的文本输出 token 数量。 diff --git a/docs/zh/api/reference/resources/images/edit-streaming-events.md b/docs/zh/api/reference/resources/images/edit-streaming-events.md index 197cf50..0137886 100644 --- a/docs/zh/api/reference/resources/images/edit-streaming-events.md +++ b/docs/zh/api/reference/resources/images/edit-streaming-events.md @@ -1,17 +1,17 @@ -# 图像编辑流式事件 +# 图片编辑流式事件 -> 如需查看完整的文档索引，请参阅 [llms.txt](/llms.txt). 通过在页面 URL 后追加 `.md` 即可获取文档页面的 Markdown 版本。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾附加 `.md` 即可获取该页面的 Markdown 版本。 -使用服务器发送事件实时流式生成和编辑图像。 -[了解更多关于图像流式传输的信息](https://developers.openai.com/docs/guides/image-generation). +使用服务端发送的事件实时流式生成和编辑图像。 +[详细了解图像流式处理](https://developers.openai.com/docs/guides/image-generation). ## image_edit.partial_image -在图像编辑流式传输期间，当部分图像可用时触发。 +在图像编辑流式传输过程中，当有部分图像可用时触发。 ### Schema -架构名称： `ImageEditPartialImageEvent` +Schema name: `ImageEditPartialImageEvent` ```json { @@ -401,11 +401,11 @@ ## image_edit.completed -当图像编辑完成且最终图像可用时触发。 +在图像编辑完成且最终图像可用时发出。 ### Schema -架构名称： `ImageEditCompletedEvent` +Schema name: `ImageEditCompletedEvent` ```json { diff --git a/docs/zh/api/reference/resources/images/generation-streaming-events.md b/docs/zh/api/reference/resources/images/generation-streaming-events.md index a14181f..f35a390 100644 --- a/docs/zh/api/reference/resources/images/generation-streaming-events.md +++ b/docs/zh/api/reference/resources/images/generation-streaming-events.md @@ -1,17 +1,17 @@ # 图像生成流式事件 -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 获得。 +> 完整的文档索引请参见 [llms.txt](/llms.txt)。可在页面 URL 末尾附加 `.md` 来获取相应文档页面的 Markdown 版本。 -使用服务器发送事件实时流式生成和编辑图像。 -[了解更多关于图像流式传输的信息](https://developers.openai.com/docs/guides/image-generation). +通过服务端发送事件实时流式生成和编辑图像。 +[详细了解图像流式传输](https://developers.openai.com/docs/guides/image-generation). ## image_generation.partial_image -在图像生成流式传输期间，当部分图像可用时发出。 +在图像生成流式传输过程中，当部分图像可用时发出。 ### Schema -Schema 名称： `ImageGenPartialImageEvent` +Schema name: `ImageGenPartialImageEvent` ```json { @@ -401,11 +401,11 @@ Schema 名称： `ImageGenPartialImageEvent` ## image_generation.completed -当图像生成已完成且最终图像可用时发出。 +当图像生成完成且最终图像可用时发出。 ### Schema -Schema 名称： `ImageGenCompletedEvent` +Schema name: `ImageGenCompletedEvent` ```json { diff --git a/docs/zh/api/reference/resources/moderations.md b/docs/zh/api/reference/resources/moderations.md index 1820c68..6097c62 100644 --- a/docs/zh/api/reference/resources/moderations.md +++ b/docs/zh/api/reference/resources/moderations.md @@ -1,68 +1,68 @@ -# 审核 +# Moderations -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 完整文档索引请参阅 [llms.txt](/llms.txt). 你可以在页面 URL 末尾追加 `.md` 来获取页面的 Markdown 版本。 ## 创建审核 **post** `/moderations` -对文本和/或图像输入是否可能有害进行分类。了解更多 -请参阅 [审核指南](/docs/guides/moderation). +对文本和/或图像输入是否可能有害进行分类。详细了解请参阅 +更多内容请参阅 [审核指南](/docs/guides/moderation). ### 请求体参数 - `input: string or array of string or array of object { image_url, type } or object { text, type }` - 要分类的输入（或输入）。可以是单个字符串、字符串数组，或 - 与其他模型类似的多模态输入对象数组。 + 用于分类的输入（或多个输入）。可以是单个字符串、字符串数组，或 + 与其他模型类似的、多模态输入对象的数组。 - `string` - 要用于审核分类的文本字符串。 + 一段需要进行审核分类的文本。 - `array of string` - 要用于审核分类的字符串数组。 + 需要进行审核分类的字符串数组。 - `array of object { image_url, type } or object { text, type }` - 提供给审核模型的多模态输入数组。 + 传递给审核模型的多模态输入数组。 - `ImageURL object { image_url, type }` - 描述要分类的图片的对象。 + 描述待分类图像的对象。 - `image_url: object { url }` - 包含图片 URL 或 base64 编码图片的数据 URL。 + 包含图像 URL 或 base64 编码图像的 data URL。 - `url: string` - 图片的 URL 或 base64 编码的图片数据。 + 图像的 URL 或 base64 编码的图像数据。 - `type: "image_url"` - 始终 `image_url`. + 始终为 `image_url`. - `"image_url"` - `Text object { text, type }` - 描述要分类的文本的对象。 + 描述待分类文本的对象。 - `text: string` - 要分类的文本字符串。 + 需要进行分类的文本字符串。 - `type: "text"` - 始终 `text`. + 始终为 `text`. - `"text"` - `model: optional string or ModerationModel` - 你希望使用的内容审核模型。了解更多，请参阅 + 你想要使用的审核模型。详情请参阅 [审核指南](/docs/guides/moderation)，并了解 可用模型 [此处](/docs/models#moderation). @@ -78,119 +78,119 @@ - `"text-moderation-stable"` -### 返回 +### Returns - `id: string` - 内容审核请求的唯一标识符。 + 审核请求的唯一标识符。 - `model: string` - 用于生成内容审核结果的模型。 + 用于生成审核结果的模型。 - `results: array of Moderation` - 内容审核对象列表。 + 审核对象的列表。 - `categories: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及每个类别是否被标记。 + 类别列表，以及它们是否被标记。 - `harassment: boolean` - 表达、煽动或宣扬针对任何目标的骚扰语言的内容。 + 针对任何目标表达、煽动或宣扬骚扰性语言的内容。 - `"harassment/threatening": boolean` - 包含针对任何目标的暴力或严重伤害的骚扰内容。 + 针对任何目标包含暴力或严重伤害的骚扰内容。 - `hate: boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如棋手）的仇恨内容属于骚扰。 + 基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如国际象棋选手）的仇恨内容属于骚扰。 - `"hate/threatening": boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓对目标群体包含暴力或严重伤害的仇恨内容。 + 针对目标群体的暴力或严重伤害的仇恨内容，基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓。 - `illicit: boolean or null` - 包含有助于规划或执行不法行为的指示或建议，或就如何实施非法行为提供建议或指导的内容。例如，“如何入店行窃”就属于该类别。 + 包含便于策划或实施违法行为的说明或建议的内容，或提供关于如何实施非法行为的建议或说明。例如，“如何商店行窃”属于此类。 - `"illicit/violent": boolean or null` - 包含有助于规划或执行不法行为（也包括暴力）的指示或建议，或就获取任何武器提供建议或指导的内容。 + 包含便于策划或实施违法行为的说明或建议（同时涉及暴力），或提供关于采购任何武器的建议或说明的内容。 - `"self-harm": boolean` - 宣扬、鼓励或描绘自残行为（如自杀、自残和饮食失调）的内容。 + 宣扬、鼓励或描述自残行为（如自杀、自残和进食障碍）的内容。 - `"self-harm/instructions": boolean` - 鼓励实施自残行为（如自杀、自残和饮食失调）的内容，或就如何实施此类行为提供指示或建议的内容。 + 鼓励实施自残行为（如自杀、自残和进食障碍），或提供关于如何实施此类行为的说明或建议的内容。 - `"self-harm/intent": boolean` - 说话者表示正在或打算实施自残行为（如自杀、自残和饮食失调）的内容。 + 说话者表示正在或打算进行自残行为（如自杀、自残和进食障碍）的内容。 - `sexual: boolean` - 旨在引起性兴奋的内容，如性活动描述，或宣扬性服务（不包括性教育和健康）的内容。 + 旨在唤起性兴奋的内容，例如对性行为的描述，或推广性服务的内容（不包括性教育和健康内容）。 - `"sexual/minors": boolean` - 包含未满18岁个人的性内容。 + 包含 18 岁以下个人的性内容。 - `violence: boolean` - 描绘死亡、暴力或身体伤害的内容。 + 描绘死亡、暴力或人身伤害的内容。 - `"violence/graphic": boolean` - 以图形细节描绘死亡、暴力或身体伤害的内容。 + 以细致图形化方式描绘死亡、暴力或人身伤害的内容。 - `category_applied_input_types: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及分数适用的输入类型。 + 类别列表以及该分数所适用的输入类型。 - `harassment: array of "text"` - 类别“harassment”适用的输入类型。 + 适用于“harassment”类别的输入类型。 - `"text"` - `"harassment/threatening": array of "text"` - 类别“harassment/threatening”适用的输入类型。 + 适用于“harassment/threatening”类别的输入类型。 - `"text"` - `hate: array of "text"` - 针对类别“hate”应用的输入类型。 + 类别 'hate' 的已应用输入类型。 - `"text"` - `"hate/threatening": array of "text"` - 针对类别“hate/threatening”应用的输入类型。 + 类别 'hate/threatening' 的已应用输入类型。 - `"text"` - `illicit: array of "text"` - 针对类别“illicit”应用的输入类型。 + 类别 'illicit' 的已应用输入类型。 - `"text"` - `"illicit/violent": array of "text"` - 针对类别“illicit/violent”应用的输入类型。 + 类别 'illicit/violent' 的已应用输入类型。 - `"text"` - `"self-harm": array of "text" or "image"` - 针对类别“self-harm”应用的输入类型。 + 类别 'self-harm' 的已应用输入类型。 - `"text"` @@ -198,7 +198,7 @@ - `"self-harm/instructions": array of "text" or "image"` - 针对类别“self-harm/instructions”应用的输入类型。 + 类别 'self-harm/instructions' 的已应用输入类型。 - `"text"` @@ -206,7 +206,7 @@ - `"self-harm/intent": array of "text" or "image"` - 针对类别“self-harm/intent”应用的输入类型。 + 类别 'self-harm/intent' 的已应用输入类型。 - `"text"` @@ -214,7 +214,7 @@ - `sexual: array of "text" or "image"` - 针对类别“sexual”应用的输入类型。 + 类别 'sexual' 的已应用输入类型。 - `"text"` @@ -222,13 +222,13 @@ - `"sexual/minors": array of "text"` - 针对类别“sexual/minors”应用的输入类型。 + 类别 'sexual/minors' 的已应用输入类型。 - `"text"` - `violence: array of "text" or "image"` - 针对类别“violence”应用的输入类型。 + 类别 'violence' 的已应用输入类型。 - `"text"` @@ -236,7 +236,7 @@ - `"violence/graphic": array of "text" or "image"` - 针对类别“violence/graphic”应用的输入类型。 + 类别 'violence/graphic' 的已应用输入类型。 - `"text"` @@ -244,63 +244,63 @@ - `category_scores: object { harassment, "harassment/threatening", hate, 10 more }` - 模型预测的类别及其分数的列表。 + 由模型预测的类别及其对应分数的列表。 - `harassment: number` - 类别“harassment”的分数。 + 类别 'harassment' 的分数。 - `"harassment/threatening": number` - 类别“harassment/threatening”的分数。 + 类别 'harassment/threatening' 的分数。 - `hate: number` - 类别“hate”的分数。 + 类别 'hate' 的分数。 - `"hate/threatening": number` - 类别“hate/threatening”的分数。 + 类别 'hate/threatening' 的分数。 - `illicit: number` - 类别“illicit”的分数。 + 类别 'illicit' 的分数。 - `"illicit/violent": number` - 类别“illicit/violent”的分数。 + 类别 'illicit/violent' 的分数。 - `"self-harm": number` - 类别“self-harm”的分数。 + 类别 'self-harm' 的分数。 - `"self-harm/instructions": number` - 类别“self-harm/instructions”的分数。 + 类别 'self-harm/instructions' 的分数。 - `"self-harm/intent": number` - 类别“自残/意图”的得分。 + 类别“self-harm/intent”的得分。 - `sexual: number` - 类别“性内容”的得分。 + 类别“sexual”的得分。 - `"sexual/minors": number` - 类别“性内容/未成年人”的得分。 + 类别“sexual/minors”的得分。 - `violence: number` - 类别“暴力”的得分。 + 类别“violence”的得分。 - `"violence/graphic": number` - 类别“暴力/血腥”的得分。 + 类别“violence/graphic”的得分。 - `flagged: boolean` - 以下任一类别是否被标记。 + 下列任一类别是否被标记。 ### 示例 @@ -313,7 +313,7 @@ curl https://api.openai.com/v1/moderations \ }' ``` -#### 响应 +#### Response ```json { @@ -398,7 +398,7 @@ curl https://api.openai.com/v1/moderations \ } ``` -### 图像和文本 +### 图片与文本 ```http curl https://api.openai.com/v1/moderations \ @@ -419,7 +419,7 @@ curl https://api.openai.com/v1/moderations \ }' ``` -#### 响应 +#### Response ```json { @@ -521,7 +521,7 @@ curl https://api.openai.com/v1/moderations \ }' ``` -#### 响应 +#### Response ```json { @@ -561,111 +561,111 @@ curl https://api.openai.com/v1/moderations \ } ``` -## 领域类型 +## Domain 类型 -### 审核 +### Moderation - `Moderation object { categories, category_applied_input_types, category_scores, flagged }` - `categories: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及每个类别是否被标记。 + 类别列表，以及它们是否被标记。 - `harassment: boolean` - 表达、煽动或宣扬针对任何目标的骚扰语言的内容。 + 针对任何目标表达、煽动或宣扬骚扰性语言的内容。 - `"harassment/threatening": boolean` - 包含针对任何目标的暴力或严重伤害的骚扰内容。 + 针对任何目标包含暴力或严重伤害的骚扰内容。 - `hate: boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如棋手）的仇恨内容属于骚扰。 + 基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如国际象棋选手）的仇恨内容属于骚扰。 - `"hate/threatening": boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓对目标群体包含暴力或严重伤害的仇恨内容。 + 针对目标群体的暴力或严重伤害的仇恨内容，基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓。 - `illicit: boolean or null` - 包含有助于规划或执行不法行为的指示或建议，或就如何实施非法行为提供建议或指导的内容。例如，“如何入店行窃”就属于该类别。 + 包含便于策划或实施违法行为的说明或建议的内容，或提供关于如何实施非法行为的建议或说明。例如，“如何商店行窃”属于此类。 - `"illicit/violent": boolean or null` - 包含有助于规划或执行不法行为（也包括暴力）的指示或建议，或就获取任何武器提供建议或指导的内容。 + 包含便于策划或实施违法行为的说明或建议（同时涉及暴力），或提供关于采购任何武器的建议或说明的内容。 - `"self-harm": boolean` - 宣扬、鼓励或描绘自残行为（如自杀、自残和饮食失调）的内容。 + 宣扬、鼓励或描述自残行为（如自杀、自残和进食障碍）的内容。 - `"self-harm/instructions": boolean` - 鼓励实施自残行为（如自杀、自残和饮食失调）的内容，或就如何实施此类行为提供指示或建议的内容。 + 鼓励实施自残行为（如自杀、自残和进食障碍），或提供关于如何实施此类行为的说明或建议的内容。 - `"self-harm/intent": boolean` - 说话者表示正在或打算实施自残行为（如自杀、自残和饮食失调）的内容。 + 说话者表示正在或打算进行自残行为（如自杀、自残和进食障碍）的内容。 - `sexual: boolean` - 旨在引起性兴奋的内容，如性活动描述，或宣扬性服务（不包括性教育和健康）的内容。 + 旨在唤起性兴奋的内容，例如对性行为的描述，或推广性服务的内容（不包括性教育和健康内容）。 - `"sexual/minors": boolean` - 包含未满18岁个人的性内容。 + 包含 18 岁以下个人的性内容。 - `violence: boolean` - 描绘死亡、暴力或身体伤害的内容。 + 描绘死亡、暴力或人身伤害的内容。 - `"violence/graphic": boolean` - 以图形细节描绘死亡、暴力或身体伤害的内容。 + 以细致图形化方式描绘死亡、暴力或人身伤害的内容。 - `category_applied_input_types: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及分数适用的输入类型。 + 类别列表以及该分数所适用的输入类型。 - `harassment: array of "text"` - 类别“harassment”适用的输入类型。 + 适用于“harassment”类别的输入类型。 - `"text"` - `"harassment/threatening": array of "text"` - 类别“harassment/threatening”适用的输入类型。 + 适用于“harassment/threatening”类别的输入类型。 - `"text"` - `hate: array of "text"` - 针对类别“hate”应用的输入类型。 + 类别 'hate' 的已应用输入类型。 - `"text"` - `"hate/threatening": array of "text"` - 针对类别“hate/threatening”应用的输入类型。 + 类别 'hate/threatening' 的已应用输入类型。 - `"text"` - `illicit: array of "text"` - 针对类别“illicit”应用的输入类型。 + 类别 'illicit' 的已应用输入类型。 - `"text"` - `"illicit/violent": array of "text"` - 针对类别“illicit/violent”应用的输入类型。 + 类别 'illicit/violent' 的已应用输入类型。 - `"text"` - `"self-harm": array of "text" or "image"` - 针对类别“self-harm”应用的输入类型。 + 类别 'self-harm' 的已应用输入类型。 - `"text"` @@ -673,7 +673,7 @@ curl https://api.openai.com/v1/moderations \ - `"self-harm/instructions": array of "text" or "image"` - 针对类别“self-harm/instructions”应用的输入类型。 + 类别 'self-harm/instructions' 的已应用输入类型。 - `"text"` @@ -681,7 +681,7 @@ curl https://api.openai.com/v1/moderations \ - `"self-harm/intent": array of "text" or "image"` - 针对类别“self-harm/intent”应用的输入类型。 + 类别 'self-harm/intent' 的已应用输入类型。 - `"text"` @@ -689,7 +689,7 @@ curl https://api.openai.com/v1/moderations \ - `sexual: array of "text" or "image"` - 针对类别“sexual”应用的输入类型。 + 类别 'sexual' 的已应用输入类型。 - `"text"` @@ -697,13 +697,13 @@ curl https://api.openai.com/v1/moderations \ - `"sexual/minors": array of "text"` - 针对类别“sexual/minors”应用的输入类型。 + 类别 'sexual/minors' 的已应用输入类型。 - `"text"` - `violence: array of "text" or "image"` - 针对类别“violence”应用的输入类型。 + 类别 'violence' 的已应用输入类型。 - `"text"` @@ -711,7 +711,7 @@ curl https://api.openai.com/v1/moderations \ - `"violence/graphic": array of "text" or "image"` - 针对类别“violence/graphic”应用的输入类型。 + 类别 'violence/graphic' 的已应用输入类型。 - `"text"` @@ -719,181 +719,181 @@ curl https://api.openai.com/v1/moderations \ - `category_scores: object { harassment, "harassment/threatening", hate, 10 more }` - 模型预测的类别及其分数的列表。 + 由模型预测的类别及其对应分数的列表。 - `harassment: number` - 类别“harassment”的分数。 + 类别 'harassment' 的分数。 - `"harassment/threatening": number` - 类别“harassment/threatening”的分数。 + 类别 'harassment/threatening' 的分数。 - `hate: number` - 类别“hate”的分数。 + 类别 'hate' 的分数。 - `"hate/threatening": number` - 类别“hate/threatening”的分数。 + 类别 'hate/threatening' 的分数。 - `illicit: number` - 类别“illicit”的分数。 + 类别 'illicit' 的分数。 - `"illicit/violent": number` - 类别“illicit/violent”的分数。 + 类别 'illicit/violent' 的分数。 - `"self-harm": number` - 类别“self-harm”的分数。 + 类别 'self-harm' 的分数。 - `"self-harm/instructions": number` - 类别“self-harm/instructions”的分数。 + 类别 'self-harm/instructions' 的分数。 - `"self-harm/intent": number` - 类别“自残/意图”的得分。 + 类别“self-harm/intent”的得分。 - `sexual: number` - 类别“性内容”的得分。 + 类别“sexual”的得分。 - `"sexual/minors": number` - 类别“性内容/未成年人”的得分。 + 类别“sexual/minors”的得分。 - `violence: number` - 类别“暴力”的得分。 + 类别“violence”的得分。 - `"violence/graphic": number` - 类别“暴力/血腥”的得分。 + 类别“violence/graphic”的得分。 - `flagged: boolean` - 以下任一类别是否被标记。 + 下列任一类别是否被标记。 -### 审核创建响应 +### Moderation 创建 Response - `ModerationCreateResponse object { id, model, results }` - 表示给定的文本输入是否可能有害。 + 表示给定文本输入是否具有潜在危害性。 - `id: string` - 内容审核请求的唯一标识符。 + 审核请求的唯一标识符。 - `model: string` - 用于生成内容审核结果的模型。 + 用于生成审核结果的模型。 - `results: array of Moderation` - 内容审核对象列表。 + 审核对象的列表。 - `categories: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及每个类别是否被标记。 + 类别列表，以及它们是否被标记。 - `harassment: boolean` - 表达、煽动或宣扬针对任何目标的骚扰语言的内容。 + 针对任何目标表达、煽动或宣扬骚扰性语言的内容。 - `"harassment/threatening": boolean` - 包含针对任何目标的暴力或严重伤害的骚扰内容。 + 针对任何目标包含暴力或严重伤害的骚扰内容。 - `hate: boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如棋手）的仇恨内容属于骚扰。 + 基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓表达、煽动或宣扬仇恨的内容。针对非受保护群体（例如国际象棋选手）的仇恨内容属于骚扰。 - `"hate/threatening": boolean` - 基于种族、性别、民族、宗教、国籍、性取向、残疾状况或种姓对目标群体包含暴力或严重伤害的仇恨内容。 + 针对目标群体的暴力或严重伤害的仇恨内容，基于种族、性别、民族、宗教、国籍、性取向、残障状况或种姓。 - `illicit: boolean or null` - 包含有助于规划或执行不法行为的指示或建议，或就如何实施非法行为提供建议或指导的内容。例如，“如何入店行窃”就属于该类别。 + 包含便于策划或实施违法行为的说明或建议的内容，或提供关于如何实施非法行为的建议或说明。例如，“如何商店行窃”属于此类。 - `"illicit/violent": boolean or null` - 包含有助于规划或执行不法行为（也包括暴力）的指示或建议，或就获取任何武器提供建议或指导的内容。 + 包含便于策划或实施违法行为的说明或建议（同时涉及暴力），或提供关于采购任何武器的建议或说明的内容。 - `"self-harm": boolean` - 宣扬、鼓励或描绘自残行为（如自杀、自残和饮食失调）的内容。 + 宣扬、鼓励或描述自残行为（如自杀、自残和进食障碍）的内容。 - `"self-harm/instructions": boolean` - 鼓励实施自残行为（如自杀、自残和饮食失调）的内容，或就如何实施此类行为提供指示或建议的内容。 + 鼓励实施自残行为（如自杀、自残和进食障碍），或提供关于如何实施此类行为的说明或建议的内容。 - `"self-harm/intent": boolean` - 说话者表示正在或打算实施自残行为（如自杀、自残和饮食失调）的内容。 + 说话者表示正在或打算进行自残行为（如自杀、自残和进食障碍）的内容。 - `sexual: boolean` - 旨在引起性兴奋的内容，如性活动描述，或宣扬性服务（不包括性教育和健康）的内容。 + 旨在唤起性兴奋的内容，例如对性行为的描述，或推广性服务的内容（不包括性教育和健康内容）。 - `"sexual/minors": boolean` - 包含未满18岁个人的性内容。 + 包含 18 岁以下个人的性内容。 - `violence: boolean` - 描绘死亡、暴力或身体伤害的内容。 + 描绘死亡、暴力或人身伤害的内容。 - `"violence/graphic": boolean` - 以图形细节描绘死亡、暴力或身体伤害的内容。 + 以细致图形化方式描绘死亡、暴力或人身伤害的内容。 - `category_applied_input_types: object { harassment, "harassment/threatening", hate, 10 more }` - 类别列表，以及分数适用的输入类型。 + 类别列表以及该分数所适用的输入类型。 - `harassment: array of "text"` - 类别“harassment”适用的输入类型。 + 适用于“harassment”类别的输入类型。 - `"text"` - `"harassment/threatening": array of "text"` - 类别“harassment/threatening”适用的输入类型。 + 适用于“harassment/threatening”类别的输入类型。 - `"text"` - `hate: array of "text"` - 针对类别“hate”应用的输入类型。 + 类别 'hate' 的已应用输入类型。 - `"text"` - `"hate/threatening": array of "text"` - 针对类别“hate/threatening”应用的输入类型。 + 类别 'hate/threatening' 的已应用输入类型。 - `"text"` - `illicit: array of "text"` - 针对类别“illicit”应用的输入类型。 + 类别 'illicit' 的已应用输入类型。 - `"text"` - `"illicit/violent": array of "text"` - 针对类别“illicit/violent”应用的输入类型。 + 类别 'illicit/violent' 的已应用输入类型。 - `"text"` - `"self-harm": array of "text" or "image"` - 针对类别“self-harm”应用的输入类型。 + 类别 'self-harm' 的已应用输入类型。 - `"text"` @@ -901,7 +901,7 @@ curl https://api.openai.com/v1/moderations \ - `"self-harm/instructions": array of "text" or "image"` - 针对类别“self-harm/instructions”应用的输入类型。 + 类别 'self-harm/instructions' 的已应用输入类型。 - `"text"` @@ -909,7 +909,7 @@ curl https://api.openai.com/v1/moderations \ - `"self-harm/intent": array of "text" or "image"` - 针对类别“self-harm/intent”应用的输入类型。 + 类别 'self-harm/intent' 的已应用输入类型。 - `"text"` @@ -917,7 +917,7 @@ curl https://api.openai.com/v1/moderations \ - `sexual: array of "text" or "image"` - 针对类别“sexual”应用的输入类型。 + 类别 'sexual' 的已应用输入类型。 - `"text"` @@ -925,13 +925,13 @@ curl https://api.openai.com/v1/moderations \ - `"sexual/minors": array of "text"` - 针对类别“sexual/minors”应用的输入类型。 + 类别 'sexual/minors' 的已应用输入类型。 - `"text"` - `violence: array of "text" or "image"` - 针对类别“violence”应用的输入类型。 + 类别 'violence' 的已应用输入类型。 - `"text"` @@ -939,7 +939,7 @@ curl https://api.openai.com/v1/moderations \ - `"violence/graphic": array of "text" or "image"` - 针对类别“violence/graphic”应用的输入类型。 + 类别 'violence/graphic' 的已应用输入类型。 - `"text"` @@ -947,63 +947,63 @@ curl https://api.openai.com/v1/moderations \ - `category_scores: object { harassment, "harassment/threatening", hate, 10 more }` - 模型预测的类别及其分数的列表。 + 由模型预测的类别及其对应分数的列表。 - `harassment: number` - 类别“harassment”的分数。 + 类别 'harassment' 的分数。 - `"harassment/threatening": number` - 类别“harassment/threatening”的分数。 + 类别 'harassment/threatening' 的分数。 - `hate: number` - 类别“hate”的分数。 + 类别 'hate' 的分数。 - `"hate/threatening": number` - 类别“hate/threatening”的分数。 + 类别 'hate/threatening' 的分数。 - `illicit: number` - 类别“illicit”的分数。 + 类别 'illicit' 的分数。 - `"illicit/violent": number` - 类别“illicit/violent”的分数。 + 类别 'illicit/violent' 的分数。 - `"self-harm": number` - 类别“self-harm”的分数。 + 类别 'self-harm' 的分数。 - `"self-harm/instructions": number` - 类别“self-harm/instructions”的分数。 + 类别 'self-harm/instructions' 的分数。 - `"self-harm/intent": number` - 类别“自残/意图”的得分。 + 类别“self-harm/intent”的得分。 - `sexual: number` - 类别“性内容”的得分。 + 类别“sexual”的得分。 - `"sexual/minors": number` - 类别“性内容/未成年人”的得分。 + 类别“sexual/minors”的得分。 - `violence: number` - 类别“暴力”的得分。 + 类别“violence”的得分。 - `"violence/graphic": number` - 类别“暴力/血腥”的得分。 + 类别“violence/graphic”的得分。 - `flagged: boolean` - 以下任一类别是否被标记。 + 下列任一类别是否被标记。 ### 审核模型 diff --git a/docs/zh/api/reference/resources/realtime/client-events.md b/docs/zh/api/reference/resources/realtime/client-events.md index f20f5fb..6b96a2f 100644 --- a/docs/zh/api/reference/resources/realtime/client-events.md +++ b/docs/zh/api/reference/resources/realtime/client-events.md @@ -1,24 +1,24 @@ -# 实时客户端事件 +# Realtime 客户端事件 -> 关于完整文档索引，请参见 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 -这些是 OpenAI Realtime WebSocket 服务器将从客户端接受的事件。 +这些事件是 OpenAI Realtime WebSocket 服务器将接受来自客户端的事件。 ## session.update 发送此事件以更新会话的配置。 -客户端可随时发送此事件以更新任何字段 -，除了 `voice` 和 `model`. `voice` 仅在尚无其他音频输出时才可更新。 +客户端可以随时发送此事件来更新任何字段 +除了 `voice` 和 `model`. `voice` 之外,只有在尚未产生其他音频输出时才能更新。 -当服务器收到 `session.update`，时，它将响应 -一个 `session.updated` 事件，显示完整且有效的配置。 -只有出现在 `session.update` 中的字段才会被更新。要清除像 -`instructions`，这样的字段，请传入空字符串。要清除像 `tools`，这样的字段，请传入空数组。 -要清除像 `turn_detection`，这样的字段，请传入 `null`. +当服务器收到一个 `session.update`，时,它会响应一个 +包含 `session.updated` 事件,显示完整且生效的配置。 +仅会更新 `session.update` 中存在的字段。若要清除类似 +`instructions`，的字段,请传递空字符串。若要清除类似 `tools`，的字段,请传递空数组。 +若要清除类似 `turn_detection`，的字段,请传递 `null`. ### Schema -Schema 名称： `RealtimeClientEventSessionUpdate` +Schema name: `RealtimeClientEventSessionUpdate` ```json { @@ -5646,23 +5646,23 @@ Schema 名称： `RealtimeClientEventSessionUpdate` ## input_audio_buffer.append -发送此事件以将音频字节附加到输入音频缓冲区。该音频 -缓冲区是你可写入并稍后提交的临时存储。“提交”将根据缓冲区内容 -在对话历史中创建新的用户消息项，并清空缓冲区。 -输入音频转录（若启用）将在缓冲区提交时生成。 +发送此事件以将音频字节追加到输入音频缓冲区。该音频 +缓冲区是可写入的临时存储，之后可以提交。“提交”操作会根据缓冲区内容在 +对话历史中创建一个新的用户消息条目，并清空缓冲区。 +（如果启用）将在缓冲区提交时生成输入音频转录。 -若启用了 VAD，音频缓冲区将用于检测语音，服务器将决定 -何时提交。当服务器端 VAD 被禁用时，你必须手动提交音频缓冲区。 -输入音频降噪作用于对音频缓冲区的写入。 +如果启用了 VAD，则使用音频缓冲区来检测语音，并由服务端决定 +何时提交。当服务端 VAD 禁用时，你必须手动提交音频缓冲区。 +输入音频降噪功能作用于对音频缓冲区的写入。 -客户端可自行决定在每次事件中放置多少音频，最多不超过 -15 MiB，例如从客户端流式传输较小的块可能使 -VAD 更加灵敏。与大多数其他客户端事件不同，服务器不会 -对该事件发送确认响应。 +客户端可以选择每次事件放入多少音频，最大不超过 +15 MiB；例如，从客户端流式传输较小的数据块可以让 +VAD 响应更及时。与大多数其他客户端事件不同，服务端 +不会为该事件发送确认响应。 ### Schema -Schema 名称： `RealtimeClientEventInputAudioBufferAppend` +Schema name: `RealtimeClientEventInputAudioBufferAppend` ```json { @@ -5769,13 +5769,13 @@ Schema 名称： `RealtimeClientEventInputAudioBufferAppend` ## input_audio_buffer.commit -发送此事件以提交用户输入音频缓冲区，这将在对话中创建一个新的用户消息项。如果输入音频缓冲区为空，此事件将产生错误。在服务端VAD模式下，客户端无需发送此事件，服务端将自动提交音频缓冲区。 +发送此事件以提交用户输入音频缓冲区，这将在对话中创建一个新的用户消息项。如果输入音频缓冲区为空，此事件将产生错误。在 Server VAD 模式下，客户端无需发送此事件，服务端会自动提交音频缓冲区。 -提交输入音频缓冲区将触发输入音频转录（如果在会话配置中启用），但不会从模型生成响应。服务端将响应一个 `input_audio_buffer.committed` 事件。 +提交输入音频缓冲区将触发输入音频转录（如果在会话配置中启用），但不会创建来自模型的响应。服务端将以一个 `input_audio_buffer.committed` 事件作出响应。 ### Schema -Schema 名称： `RealtimeClientEventInputAudioBufferCommit` +Schema name: `RealtimeClientEventInputAudioBufferCommit` ```json { @@ -5863,12 +5863,12 @@ Schema 名称： `RealtimeClientEventInputAudioBufferCommit` ## input_audio_buffer.clear -发送此事件以清除缓冲区中的音频字节。服务器将 -以以下内容响应 `input_audio_buffer.cleared` 事件。 +发送该事件以清空缓冲区中的音频字节。服务端将 +以以下响应作出回复 `input_audio_buffer.cleared` 事件作出响应。 ### Schema -Schema 名称： `RealtimeClientEventInputAudioBufferClear` +Schema name: `RealtimeClientEventInputAudioBufferClear` ```json { @@ -5956,17 +5956,17 @@ Schema 名称： `RealtimeClientEventInputAudioBufferClear` ## conversation.item.create -向 Conversation 的上下文中添加一个新 Item，包括消息、函数 -调用和函数调用响应。此事件既可用来填充对话的 -“历史记录”，也可在流式传输过程中添加新条目，但存在一个 -当前的限制：它无法填充 assistant 音频消息。 +向会话上下文中添加一个新 Item，包括消息、函数 +调用和函数调用响应。该事件既可用于填充会话的 +“历史记录”，也可用于在流式传输过程中添加新的 Item，但存在 +当前限制：无法填充助手音频消息。 -如果成功，服务器将响应一个 `conversation.item.created` +如果成功，服务端将响应一个 `conversation.item.created` 事件，否则将发送一个 `error` 事件。 ### Schema -Schema 名称： `RealtimeClientEventConversationItemCreate` +Schema name: `RealtimeClientEventConversationItemCreate` ```json { @@ -8651,14 +8651,14 @@ Schema 名称： `RealtimeClientEventConversationItemCreate` ## conversation.item.retrieve -当你希望检索对话历史中特定条目的服务端表示时，发送此事件。例如，这在检查经过噪音消除和 VAD 处理后的用户音频时非常有用。 -服务器将响应一个 `conversation.item.retrieved` 事件， -除非该条目不存在于对话历史中，在这种情况下， -服务器将响应一个错误。 +当你希望获取服务器对会话历史中某一项的表示时，发送此事件。例如，可用于在降噪和 VAD 之后检查用户音频。 +服务器将返回一个 `conversation.item.retrieved` 事件， +除非该项不存在于会话历史中，此时 +服务器将返回错误。 ### Schema -Schema 名称： `RealtimeClientEventConversationItemRetrieve` +Schema name: `RealtimeClientEventConversationItemRetrieve` ```json { @@ -8765,21 +8765,21 @@ Schema 名称： `RealtimeClientEventConversationItemRetrieve` ## conversation.item.truncate -发送此事件可截断先前助手消息的音频。服务器 -生成音频的速度将快于实时，因此当用户 -打断以截断已发送给客户端但尚未播放的音频时，此事件非常有用。 -这将使服务器对音频的理解与 -客户端的播放保持同步。 +发送此事件以截断之前的助手消息的音频。服务器 +生成音频的速度快于实时，因此当用户中断以截断已经发送给 +客户端但尚未播放的音频时，该事件非常有用。这会将服务器对 +音频的理解与客户端的播放同步起来。 +客户端的播放同步起来。 -截断音频将删除服务端的文本转录，以确保 -上下文中没有用户尚未听到的文本。 +截断音频将删除服务端 文本转录，以确保上下文中 +不会出现用户尚未听到的文本。 -如果成功，服务器将响应一个 `conversation.item.truncated` -事件。 +如果成功，服务端将响应一个 `conversation.item.truncated` +事件作出响应。 ### Schema -Schema 名称： `RealtimeClientEventConversationItemTruncate` +Schema name: `RealtimeClientEventConversationItemTruncate` ```json { @@ -8924,14 +8924,14 @@ Schema 名称： `RealtimeClientEventConversationItemTruncate` ## conversation.item.delete -当你想要从对话中移除任何条目时，发送此事件 -历史记录。服务器将响应一个 `conversation.item.deleted` 事件， -除非该条目不存在于对话历史中，在这种情况下， -服务器将响应一个错误。 +当你想从对话历史中移除任何条目时发送该事件 +。服务端将响应一个 `conversation.item.deleted` 事件， +除非该项不存在于会话历史中，此时 +服务器将返回错误。 ### Schema -Schema 名称： `RealtimeClientEventConversationItemDelete` +Schema name: `RealtimeClientEventConversationItemDelete` ```json { @@ -9038,35 +9038,35 @@ Schema 名称： `RealtimeClientEventConversationItemDelete` ## response.create -此事件指示服务器创建 Response，这意味着触发 -模型推理。当处于服务器端 VAD 模式时，服务器将自动创建 -Responses。 +此事件指示服务端创建一个 Response，即触发 +模型推理。在 Server VAD 模式下，服务端会自动创建 Response +。 -一个 Response 将至少包含一个 Item，也可能包含两个，在这种情况下 -第二个将是函数调用。这些 Item 将默认追加到 +一个 Response 至少包含一个 Item，也可能有两个，此时 +第二个将是一个函数调用。这些 Item 默认会被追加到 对话历史中。 -服务器将响应一个 `response.created` 事件，以及为 Items -和创建的内容生成的事件，最后是一个 `response.done` 事件来表示 +服务器将返回一个 `response.created` 事件、Items 事件 +以及已创建内容的事件，最后是一个 `response.done` 事件以指示 Response 已完成。 该 `response.create` 事件包含推理配置，例如 -`instructions` 和 `tools`。如果设置了这些配置，它们将仅为此 Response 覆盖会话的 +`instructions` 和 `tools`。如果设置了，它们将仅针对此次 Response 覆盖 Session 的 配置。 -Responses 可以在默认会话之外创建，这意味着它们可以 -具有任意输入，并且可以禁用将输出写入会话。 -一次只能有一个 Response 写入默认会话，但除此之外，多个 -Responses 可以并行创建。该 `metadata` 字段是消除 -多个同时进行的 Responses 歧义的好方法。 +Response 可以在默认 Conversation 之外创建，这意味着它们可以 +包含任意输入，并且可以禁用将输出写入到 Conversation。 +默认 Conversation 同一时间只能由一个 Response 写入，但除此之外可以并行创建多个 +Response。 `metadata` 字段是区分 +同时进行的多个 Response 的好方法。 -客户端可以设置 `conversation` 为 `none` 以创建不写入默认 -对话的响应。可以通过 `input` 字段提供任意输入，该字段是一个数组，接受 -原始条目和对现有条目的引用。 +客户端可以设置 `conversation` 以 `none` 来创建一个不会写入默认 +会话的 Response。可以通过 `input` 字段提供任意输入，该字段是一个接受 +原始 Items 和对现有 Items 引用的数组。 ### Schema -Schema 名称： `RealtimeClientEventResponseCreate` +Schema name: `RealtimeClientEventResponseCreate` ```json { @@ -14798,15 +14798,15 @@ Schema 名称： `RealtimeClientEventResponseCreate` ## response.cancel -发送此事件以取消进行中的响应。服务器将响应 -一个 `response.done` 一个状态为 `response.status=cancelled`。的事件。如果 -没有要取消的响应，服务器将返回错误。即使 -调用 `response.cancel` 时没有进行中的响应，也会返回错误，但 +发送此事件以取消进行中的响应。服务端将响应 +包含 `response.done` 状态为 `response.status=cancelled`。的事件。如果 +没有可取消的响应，服务端将返回错误。即使 +调用 `response.cancel` 时没有响应正在进行，也会返回错误， 会话将不受影响。 ### Schema -Schema 名称： `RealtimeClientEventResponseCancel` +Schema name: `RealtimeClientEventResponseCancel` ```json { @@ -14912,15 +14912,15 @@ Schema 名称： `RealtimeClientEventResponseCancel` ## output_audio_buffer.clear -**仅 WebRTC/SIP：** 发出以切断当前的音频响应。这将触发服务器 -停止生成音频并发出 `output_audio_buffer.cleared` 事件。该 -事件之前应有一个 `response.cancel` 客户端事件来停止 -当前响应的生成。 +**仅限 WebRTC/SIP：** 发送以切断当前的音频响应。这将触发服务器 +停止生成音频并发出一个 `output_audio_buffer.cleared` 事件。此 +事件应之前发送一个 `response.cancel` 客户端事件以停止当前响应 +的生成。 [了解更多](https://developers.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). ### Schema -Schema 名称： `RealtimeClientEventOutputAudioBufferClear` +Schema name: `RealtimeClientEventOutputAudioBufferClear` ```json { diff --git a/docs/zh/api/reference/resources/realtime/server-events.md b/docs/zh/api/reference/resources/realtime/server-events.md index 572284b..f937104 100644 --- a/docs/zh/api/reference/resources/realtime/server-events.md +++ b/docs/zh/api/reference/resources/realtime/server-events.md @@ -1,16 +1,16 @@ -# 实时服务器事件 +# Realtime server events -> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。可在页面 URL 末尾添加 `.md` 来获取文档页面的 Markdown 版本。 -这些是从 OpenAI Realtime WebSocket 服务器发送到客户端的事件。 +这些事件是从 OpenAI 实时 WebSocket 服务器向客户端发出的事件。 ## conversation.created -在对话创建时返回。在会话创建后立即发出。 +在创建对话时返回。紧跟在会话创建之后发出。 ### Schema -架构名称： `RealtimeServerEventConversationCreated` +Schema 名称： `RealtimeServerEventConversationCreated` ```json { @@ -142,7 +142,7 @@ } ``` -### 示例 +### Example ```json { @@ -157,19 +157,19 @@ ## conversation.item.created -当创建对话项目时返回。有几种场景会产生此事件： - - 服务器正在生成一个 Response，如果成功将产生 - 一个或两个 Item，其类型为 `message` +在对话条目被创建时返回。产生该事件的情形有以下几种： + - 服务器正在生成一个 Response，如果成功，将生成 + 一个或两个 Items，它们的类型为 `message` (role `assistant`) 或类型 `function_call`. - - 输入音频缓冲区已被提交，无论是客户端还是服务器（在 - 模式） `server_vad` 。服务器将把 - 输入音频缓冲区的内容添加到新的用户消息 Item 中。 - - 客户端已发送一个 `conversation.item.create` 事件以将新的 Item - 添加到会话中。 + - 输入音频缓冲区已被提交，由客户端或 + 服务器提交（处于 `server_vad` 模式下）。服务器将获取输入音频缓冲区的内容，并将其添加到一条新的用户消息 Item 中。 + 输入音频缓冲区并将其添加到一条新的用户消息 Item 中。 + - 客户端已发送一个 `conversation.item.create` 事件以向该对话添加一个新的 Item + 到该对话中。 ### Schema -架构名称： `RealtimeServerEventConversationItemCreated` +Schema 名称： `RealtimeServerEventConversationItemCreated` ```json { @@ -2831,7 +2831,7 @@ } ``` -### 示例 +### Example ```json { @@ -2851,13 +2851,13 @@ ## conversation.item.deleted -当客户端通过 -`conversation.item.delete` 事件删除对话中的某个项目时返回。此事件用于同步 -服务器对对话历史的理解与客户端的视图。 +当会话中的某一项被客户端通过以下事件删除时返回： +`conversation.item.delete` 事件。该事件用于同步服务端 +对会话历史的理解与客户端的视图。 ### Schema -架构名称： `RealtimeServerEventConversationItemDeleted` +Schema 名称： `RealtimeServerEventConversationItemDeleted` ```json { @@ -2949,7 +2949,7 @@ } ``` -### 示例 +### Example ```json { @@ -2961,20 +2961,20 @@ ## conversation.item.input_audio_transcription.completed -此事件是写入 -用户音频缓冲区的音频转录输出。转录在输入音频缓冲区由客户端或服务器提交时（启用 VAD 时）开始。转录与响应创建异步进行，因此此事件可能出现在响应事件之前或之后。 -客户端或服务器提交输入音频缓冲区时（启用 VAD 时）开始转录。转录运行 -与响应创建异步，因此此事件可能出现在 -响应事件之前或之后。 +此事件是写入到用户音频缓冲区的用户音频转录输出 +的输出结果。当输入音频缓冲区被提交时，转录开始。 +提交方可以是客户端，也可以是服务端（启用 VAD 时）。转录与 Response 创建 +异步进行，因此该事件可能先于或后于 Response 事件到达。 +Response 事件一起出现。 -Realtime API 模型原生接受音频，因此输入转录是 -在单独的 ASR（自动语音识别）模型上运行的独立过程。 -转录文本可能与模型的解释有所不同， -应视为粗略指南。 +Realtime API 模型原生支持音频，因此输入转录是一个 +独立的流程，在单独的 ASR（自动语音识别）模型上运行。 +转录文本可能与模型的解读存在一定差异， +应视为大致参考。 ### Schema -架构名称： `RealtimeServerEventConversationItemInputAudioTranscriptionCompleted` +Schema 名称： `RealtimeServerEventConversationItemInputAudioTranscriptionCompleted` ```json { @@ -3549,7 +3549,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -3573,11 +3573,11 @@ Realtime API 模型原生接受音频，因此输入转录是 ## conversation.item.input_audio_transcription.delta -当输入音频转录内容部分的文本值通过增量转录结果更新时返回。 +当输入音频转录内容部分的文本值使用增量转录结果更新时返回。 ### Schema -架构名称： `RealtimeServerEventConversationItemInputAudioTranscriptionDelta` +Schema 名称： `RealtimeServerEventConversationItemInputAudioTranscriptionDelta` ```json { @@ -3806,7 +3806,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -3821,13 +3821,13 @@ Realtime API 模型原生接受音频，因此输入转录是 ## conversation.item.input_audio_transcription.failed -当配置了输入音频转录，且用户消息的转录 -请求失败时返回。这些事件与其他事件分开 -`error` 返回，以便客户端能够识别相关的条目。 +在配置了输入音频转写时返回，表示用户消息的转写 +请求失败。这些事件与其他事件分开，以便客户端能够识别相关的 Item。 +`error` 事件，以便客户端识别相关的 Item。 ### Schema -架构名称： `RealtimeServerEventConversationItemInputAudioTranscriptionFailed` +Schema 名称： `RealtimeServerEventConversationItemInputAudioTranscriptionFailed` ```json { @@ -4031,7 +4031,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -4050,11 +4050,11 @@ Realtime API 模型原生接受音频，因此输入转录是 ## conversation.item.retrieved -当会话条目通过以下方式检索时返回 `conversation.item.retrieve`。这提供了一种获取条目在服务端表示的方法，例如在噪声消除和VAD之后访问后处理的音频数据。它包含该条目的完整内容，包括音频数据。 +检索对话项时返回 `conversation.item.retrieve`。这提供了一种获取服务端对项的表示形式的方法，例如在降噪和 VAD 后访问经过后处理的音频数据。其中包含项的完整内容，包括音频数据。 ### Schema -架构名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 6` +Schema 名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 6` ```json { @@ -6698,7 +6698,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json {} @@ -6706,16 +6706,16 @@ Realtime API 模型原生接受音频，因此输入转录是 ## conversation.item.truncated -当较早的助手音频消息项被客户端截断时返回， -客户端通过 `conversation.item.truncate` 事件。此事件用于 -同步服务器对音频的理解与客户端的播放。 +当较早的助手音频消息项被客户端通过 +事件截断时返回。 `conversation.item.truncate` 该事件用于 +使服务端对音频的理解与客户端的播放保持同步。 -此操作将截断音频并移除服务端文本转录 -，以确保上下文中没有用户未听到的文本。 +此操作将截断音频，并移除 服务端 文本转录， +以确保上下文中不存在用户尚未听到的文本。 ### Schema -架构名称： `RealtimeServerEventConversationItemTruncated` +Schema 名称： `RealtimeServerEventConversationItemTruncated` ```json { @@ -6843,7 +6843,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -6857,13 +6857,13 @@ Realtime API 模型原生接受音频，因此输入转录是 ## error -当发生错误时返回，可能是客户端问题或服务器 -问题。大多数错误是可恢复的，会话将保持打开，我们 -建议实现者默认监控和记录错误消息。 +在发生错误时返回，错误可能由客户端或服务端 +引起。大多数错误都是可恢复的，会话将保持打开状态，我们 +建议实现者默认监控并记录错误消息。 ### Schema -架构名称： `RealtimeServerEventError` +Schema 名称： `RealtimeServerEventError` ```json { @@ -7070,7 +7070,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -7088,12 +7088,12 @@ Realtime API 模型原生接受音频，因此输入转录是 ## input_audio_buffer.cleared -当客户端通过 -`input_audio_buffer.clear` 事件清除输入音频缓冲区时返回。 +当客户端通过以下方式清除输入音频缓冲区时返回 +`input_audio_buffer.clear` event。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferCleared` +Schema 名称： `RealtimeServerEventInputAudioBufferCleared` ```json { @@ -7167,7 +7167,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -7178,14 +7178,14 @@ Realtime API 模型原生接受音频，因此输入转录是 ## input_audio_buffer.committed -当输入音频缓冲区被提交时返回，无论是客户端提交还是 -在服务端 VAD 模式下自动提交。该 `item_id` 属性是将要创建的用户 -消息项的 ID，因此一个 `conversation.item.created` 事件 -也将发送给客户端。 +在输入音频缓冲区被提交时返回，可以由客户端触发，也可以由 +服务端 VAD 模式自动触发。该 `item_id` 属性是用户消息项的 ID，因此 +同时也会向客户端发送一个 `conversation.item.created` event +事件。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferCommitted` +Schema 名称： `RealtimeServerEventInputAudioBufferCommitted` ```json { @@ -7295,7 +7295,7 @@ Realtime API 模型原生接受音频，因此输入转录是 } ``` -### 示例 +### Example ```json { @@ -7308,14 +7308,14 @@ Realtime API 模型原生接受音频，因此输入转录是 ## input_audio_buffer.dtmf_event_received -**仅 SIP：** 当收到 DTMF 事件时返回。DTMF 事件是一条消息， -表示电话键盘按键（0–9、*、#、A–D）。 `event` 属性 -是用户按下的按键。事件中的 `received_at` 是服务器收到事件的 -UTC Unix 时间戳。 +**SIP Only：** 在收到 DTMF 事件时返回。DTMF 事件是一种表示电话键盘按键（0–9、*、#、A–D）的消息。 +属性表示用户按下的按键。 `event` property +是用户按下的键盘按键。 `received_at` 是服务端收到事件的 UTC Unix 时间戳。 +即服务端收到事件的时间。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferDtmfEventReceived` +Schema 名称： `RealtimeServerEventInputAudioBufferDtmfEventReceived` ```json { @@ -7407,7 +7407,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -7419,20 +7419,20 @@ UTC Unix 时间戳。 ## input_audio_buffer.speech_started -当服务器处于 `server_vad` 模式时发送，表示音频缓冲区中已 -检测到语音。这可能在音频被添加到缓冲区时随时发生 -（除非已检测到语音）。客户端可能希望使用此事件 -来中断音频播放或向用户提供视觉反馈。 +由服务端在 `server_vad` 模式下发送，用于指示已在音频缓冲区中检测到语音。 +检测到语音。只要音频被添加到缓冲区（除非已经检测到语音），就可能发生该事件。客户端可能希望使用该 +事件来中断音频播放或向用户提供可视化反馈。 +客户端应预期在语音停止时收到。 -客户端应期望在语音停止时收到 `input_audio_buffer.speech_stopped` 事件 -事件。该 `item_id` 属性是语音停止时将创建的用户消息项的 ID， -该 ID 也将包含在 +一个 `input_audio_buffer.speech_stopped` event +事件。 `item_id` 属性是用户消息项的 ID， +该用户消息项将在语音停止时创建，并且也将包含在 `input_audio_buffer.speech_stopped` 事件中（除非客户端在 VAD 激活期间手动提交 音频缓冲区）。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferSpeechStarted` +Schema 名称： `RealtimeServerEventInputAudioBufferSpeechStarted` ```json { @@ -7542,7 +7542,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -7555,13 +7555,13 @@ UTC Unix 时间戳。 ## input_audio_buffer.speech_stopped -在 `server_vad` 模式下，当服务端检测到 -音频缓冲区中的语音结束时，服务器还会发送一个 `conversation.item.created` -事件，其中包含从音频缓冲区创建的用户消息条目。 +在 `server_vad` 当服务端在以下音频缓冲区中检测到语音结束时返回的 +模式。服务端还会发送一个 `conversation.item.created` +事件，其中包含从音频缓冲区创建的用户消息项。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferSpeechStopped` +Schema 名称： `RealtimeServerEventInputAudioBufferSpeechStopped` ```json { @@ -7671,7 +7671,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -7684,14 +7684,14 @@ UTC Unix 时间戳。 ## rate_limits.updated -在响应开始时发出，以指示更新后的速率限制。 -创建响应时，一些令牌将被“保留”用于输出 -令牌，此处显示的速率限制反映了该保留，然后在 -响应完成后相应调整。 +在 Response 开始时发出，用于指示已更新的速率限制。 +创建 Response 时，会为输出"预留"一部分 tokens +此处显示的速率限制反映了该预留，并在 +Response 完成后相应地进行调整。 ### Schema -架构名称： `RealtimeServerEventRateLimitsUpdated` +Schema 名称： `RealtimeServerEventRateLimitsUpdated` ```json { @@ -7892,7 +7892,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -7917,11 +7917,11 @@ UTC Unix 时间戳。 ## response.output_audio.delta -当模型生成的音频被更新时返回。 +在模型生成的音频被更新时返回。 ### Schema -架构名称： `RealtimeServerEventResponseAudioDelta` +Schema 名称： `RealtimeServerEventResponseAudioDelta` ```json { @@ -8085,7 +8085,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -8101,12 +8101,12 @@ UTC Unix 时间戳。 ## response.output_audio.done -当模型生成的音频完成时返回。当 Response -被中断、未完成或取消时也会发出。 +当模型生成的音频完成时返回。在 Response 中断时也会发出 +已中断、未完成或被取消。 ### Schema -架构名称： `RealtimeServerEventResponseAudioDone` +Schema 名称： `RealtimeServerEventResponseAudioDone` ```json { @@ -8252,7 +8252,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -8267,11 +8267,11 @@ UTC Unix 时间戳。 ## response.output_audio_transcript.delta -当模型生成的音频输出转录更新时返回。 +当音频输出的模型生成转录被更新时返回。 ### Schema -架构名称： `RealtimeServerEventResponseAudioTranscriptDelta` +Schema 名称： `RealtimeServerEventResponseAudioTranscriptDelta` ```json { @@ -8435,7 +8435,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -8452,12 +8452,12 @@ UTC Unix 时间戳。 ## response.output_audio_transcript.done 当模型生成的音频输出转录完成时返回 -流式传输。当 Response 被中断、不完整或 -取消时也会发出。 +streaming。也会在 Response 被中断、未完成或 +取消时发出。 ### Schema -架构名称： `RealtimeServerEventResponseAudioTranscriptDone` +Schema 名称： `RealtimeServerEventResponseAudioTranscriptDone` ```json { @@ -8621,7 +8621,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -8637,12 +8637,12 @@ UTC Unix 时间戳。 ## response.content_part.added -当在助手消息条目中添加新内容部分时返回，该条目发生于 -响应生成期间。 +在响应生成过程中，当新的内容片段被添加到助手消息项时返回。 +响应生成。 ### Schema -架构名称： `RealtimeServerEventResponseContentPartAdded` +Schema 名称： `RealtimeServerEventResponseContentPartAdded` ```json { @@ -8911,7 +8911,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -8930,12 +8930,12 @@ UTC Unix 时间戳。 ## response.content_part.done -当智能体消息项中的内容部分完成流式传输时返回。 -当响应被中断、不完整或取消时也会发出。 +当内容片段在智能体消息条目中流式传输完成时返回。 +也会在 Response 被中断、未完成或取消时发出。 ### Schema -架构名称： `RealtimeServerEventResponseContentPartDone` +Schema 名称： `RealtimeServerEventResponseContentPartDone` ```json { @@ -9204,7 +9204,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -9223,12 +9223,12 @@ UTC Unix 时间戳。 ## response.created -在创建新 Response 时返回。这是响应创建过程中的第一个事件， -此时响应处于初始状态， `in_progress`. +在创建新 Response 时返回。响应创建的第一个事件， +其中响应处于初始状态 `in_progress`. ### Schema -架构名称： `RealtimeServerEventResponseCreated` +Schema 名称： `RealtimeServerEventResponseCreated` ```json { @@ -13367,7 +13367,7 @@ UTC Unix 时间戳。 } ``` -### 示例 +### Example ```json { @@ -13401,19 +13401,19 @@ UTC Unix 时间戳。 ## response.done -当响应完成流式传输时返回。无论最终 -状态如何，都会始终发出。包含在 `response.done` 事件中的 -Response 对象将包含响应中的所有输出项，但会省略原始音频数据。 +当 Response 完成流式传输时返回。无论最终状态如何，都会被发出， +在 `response.done` 事件中将包含 +Response 中的所有输出 Item，但会省略原始音频数据。 -客户端应检查 Response 的 `status` 字段，以确定它是否成功 -(`completed`）或是否存在其他结果： `cancelled`, `failed`，或 `incomplete`. +客户端应检查 Response 的 `status` 字段以判断是否成功 +(`completed`) 或是否出现了其他结果： `cancelled`, `failed`，或 `incomplete`. -响应将包含在响应期间生成的所有输出项，不包括 +响应将包含在响应过程中生成的所有输出项，不包括 任何音频内容。 ### Schema -架构名称： `RealtimeServerEventResponseDone` +Schema 名称： `RealtimeServerEventResponseDone` ```json { @@ -17552,7 +17552,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -17622,7 +17622,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ### Schema -架构名称： `RealtimeServerEventResponseFunctionCallArgumentsDelta` +Schema 名称： `RealtimeServerEventResponseFunctionCallArgumentsDelta` ```json { @@ -17786,7 +17786,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -17802,12 +17802,12 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.function_call_arguments.done -当模型生成的函数调用参数流式传输完成时返回。 -当响应被中断、不完整或取消时也会发出。 +在模型生成的函数调用参数流式传输完成时返回。 +也会在 Response 被中断、未完成或取消时发出。 ### Schema -架构名称： `RealtimeServerEventResponseFunctionCallArgumentsDone` +Schema 名称： `RealtimeServerEventResponseFunctionCallArgumentsDone` ```json { @@ -17989,7 +17989,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -18006,11 +18006,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.output_item.added -在 Response 生成期间创建新 Item 时返回。 +在 Response 生成过程中创建新 Item 时返回。 ### Schema -架构名称： `RealtimeServerEventResponseOutputItemAdded` +Schema 名称： `RealtimeServerEventResponseOutputItemAdded` ```json { @@ -20690,7 +20690,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -20711,12 +20711,12 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.output_item.done -当 Item 完成流式传输时返回。当 Response -被中断、未完成或取消时也会发出。 +当一个 Item 完成流式传输时返回。也会在 Response 被 +中断、未完成或被取消时发出。 ### Schema -架构名称： `RealtimeServerEventResponseOutputItemDone` +Schema 名称： `RealtimeServerEventResponseOutputItemDone` ```json { @@ -23396,7 +23396,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -23422,11 +23422,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.output_text.delta -当 "output_text" 内容部分的文本值被更新时返回。 +当 "output_text" 内容部分的文本值更新时返回。 ### Schema -架构名称： `RealtimeServerEventResponseTextDelta` +Schema 名称： `RealtimeServerEventResponseTextDelta` ```json { @@ -23590,7 +23590,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -23606,12 +23606,12 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.output_text.done -当“output_text”内容部件的文本值完成流式传输时返回。同时 -在响应被中断、不完整或取消时发出。 +当 "output_text" 内容部分的文本值完成流式传输时返回。另 +外，当 Response 被中断、未完成或被取消时也会触发。 ### Schema -架构名称： `RealtimeServerEventResponseTextDone` +Schema 名称： `RealtimeServerEventResponseTextDone` ```json { @@ -23775,7 +23775,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -23791,13 +23791,13 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## session.created -在创建 Session 时返回。在新 -连接建立时自动作为第一个服务器事件发出。此事件将包含 +创建 Session 时返回。建立新连接后，作为第一个服务端事件自动发出 +该事件将包含 默认的 Session 配置。 ### Schema -架构名称： `RealtimeServerEventSessionCreated` +Schema 名称： `RealtimeServerEventSessionCreated` ```json { @@ -29090,7 +29090,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -29145,12 +29145,12 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## session.updated -当会话更新时返回 `session.update` 事件，除非 -发生错误。 +当会话通过以下事件更新时返回： `session.update` event，除非 +出现错误。 ### Schema -架构名称： `RealtimeServerEventSessionUpdated` +Schema 名称： `RealtimeServerEventSessionUpdated` ```json { @@ -34443,7 +34443,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -34526,14 +34526,14 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## output_audio_buffer.started -**仅限 WebRTC/SIP：** 当服务器开始向客户端流式传输音频时触发。此事件在 -音频内容部分被添加（`response.content_part.added`) -到响应中）之后触发。 +**仅限 WebRTC/SIP：** 当服务器开始向客户端流式传输音频时发出。该事件 +在音频内容部分被添加后发出（`response.content_part.added`) +到响应中。 [了解更多](https://developers.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). ### Schema -架构名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 31` +Schema 名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 31` ```json { @@ -34625,7 +34625,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json {} @@ -34633,14 +34633,14 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## output_audio_buffer.stopped -**仅限 WebRTC/SIP：** 当服务端输出音频缓冲区已完全耗尽时发出该事件， -且后续不会再产生更多音频。此事件在完整响应 -数据已发送给客户端（`response.done`). +**仅限 WebRTC/SIP：** 当服务端上的输出音频缓冲已被完全耗尽时发出， +且不再有音频输出。此事件在完整响应 +数据已发送到客户端后发出（`response.done`). [了解更多](https://developers.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). ### Schema -架构名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 32` +Schema 名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 32` ```json { @@ -34732,7 +34732,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json {} @@ -34740,15 +34740,15 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## output_audio_buffer.cleared -**仅限 WebRTC/SIP：** 当输出音频缓冲区被清除时发出。这发生在 VAD -模式下，当用户打断（`input_audio_buffer.speech_started`), -或当客户端发出 `output_audio_buffer.clear` 事件以手动 -切断当前音频响应时。 +**仅限 WebRTC/SIP：** 当输出音频缓冲区被清除时触发。这种情况发生在 VAD +模式下用户发生打断时（`input_audio_buffer.speech_started`), +），或者当客户端触发了 `output_audio_buffer.clear` 事件以手动 +截断当前音频响应。 [了解更多](https://developers.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). ### Schema -架构名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 33` +Schema 名称： `(resource) realtime > (model) realtime_server_event > (schema) > (variant) 33` ```json { @@ -34840,7 +34840,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json {} @@ -34848,16 +34848,16 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## conversation.item.added -服务器在项目被添加到默认对话时发送此消息。这可能在以下几种情况下发生： +当某个 Item 被添加到默认会话时由服务端发送。这种情况可能在以下几种场景中发生： - 当客户端发送 `conversation.item.create` 事件时。 -- 当输入音频缓冲区被提交时。在这种情况下，条目将是一条包含缓冲区中音频的用户消息。 -- 当模型正在生成响应时。在这种情况下， `conversation.item.added` 事件将在模型开始生成特定条目时发送，因此此时该条目尚不会有任何内容（并且 `status` 将为 `in_progress`). +- 当输入音频缓冲区被提交时。在这种情况下，该 item 将是一条包含缓冲区中音频的用户消息。 +- 当模型正在生成 Response 时。在这种情况下， `conversation.item.added` 事件将在模型开始生成特定 Item 时发送，因此此时它还不会有任何内容（并且 `status` 将 `in_progress`). -该事件将包含项目的完整内容（模型生成响应时除外），但音频数据除外，音频数据可单独通过 `conversation.item.retrieve` 事件获取（如有必要）。 +该事件将包含 Item 的完整内容（模型正在生成 Response 时除外），但音频数据除外，音频数据可以通过以下事件单独获取： `conversation.item.retrieve` 事件（如有必要）。 ### Schema -架构名称： `RealtimeServerEventConversationItemAdded` +Schema 名称： `RealtimeServerEventConversationItemAdded` ```json { @@ -37519,7 +37519,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -37543,13 +37543,13 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## conversation.item.done -当会话项目完成时返回。 +当对话条目被最终化时返回。 -该事件将包含项目的完整内容，音频数据除外，音频数据可通过 `conversation.item.retrieve` 事件单独检索（如需要）。 +该事件将包含条目的完整内容，但音频数据除外，音频数据可以单独通过以下方式获取： `conversation.item.retrieve` 事件（如有需要）。 ### Schema -架构名称： `RealtimeServerEventConversationItemDone` +Schema 名称： `RealtimeServerEventConversationItemDone` ```json { @@ -40211,7 +40211,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40235,23 +40235,23 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## input_audio_buffer.timeout_triggered -当输入音频缓冲区触发服务器端 VAD 超时时返回。这是通过 -会话的 `idle_timeout_ms` 设置 `turn_detection` 配置的，它表示 -在配置的时长内没有检测到任何语音。 +在输入音频缓冲区触发 Server VAD 超时时返回。该超时通过会话的 +在 `idle_timeout_ms` 中的 `turn_detection` 设置进行配置，表示在配置的持续时间内 +未检测到任何语音。 -该 `audio_start_ms` 和 `audio_end_ms` 字段表示最后一次 -模型响应之后到触发时刻之间的音频片段，以写入 -输入音频缓冲区的起始偏移量表示。这意味着它划分了静音的音频片段，并且 -起始值和结束值之间的差异将大致与配置的超时时间匹配。 +该 `audio_start_ms` 和 `audio_end_ms` 字段表示从最后一个 +模型响应之后到触发时间为止的音频片段，以写入输入音频缓冲区 +的音频开头为偏移量。这意味着它划定了处于静默状态的片段， +且 start 与 end 之间的差值大致与所配置的超时一致。 -空的音频将被作为 `input_audio` 项提交到对话中（将有一个 -`input_audio_buffer.committed` 事件），并且将生成模型响应。可能会有语音 -未触发 VAD，但模型仍会检测到，因此模型可能会响应 -与对话相关的内容或提示继续说话。 +这段空音频将以 `input_audio` 项的形式提交到对话中（会触发一个 +`input_audio_buffer.committed` 事件），并生成模型响应。可能存在一些语音 +未触发 VAD 但仍被模型检测到，因此模型可能给出 +与对话相关的内容或提示你继续说话。 ### Schema -架构名称： `RealtimeServerEventInputAudioBufferTimeoutTriggered` +Schema 名称： `RealtimeServerEventInputAudioBufferTimeoutTriggered` ```json { @@ -40379,7 +40379,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40393,11 +40393,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## conversation.item.input_audio_transcription.segment -当某项的输入音频转录片段被识别时返回。 +当为某个 item 识别出输入音频转写片段时返回。 ### Schema -架构名称： `RealtimeServerEventConversationItemInputAudioTranscriptionSegment` +Schema 名称： `RealtimeServerEventConversationItemInputAudioTranscriptionSegment` ```json { @@ -40603,7 +40603,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40621,11 +40621,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## mcp_list_tools.in_progress -当某个条目的 MCP 工具列表正在进行时返回。 +当某个条目的 MCP 工具列表正在获取时返回。 ### Schema -架构名称： `RealtimeServerEventMCPListToolsInProgress` +Schema 名称： `RealtimeServerEventMCPListToolsInProgress` ```json { @@ -40717,7 +40717,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40729,11 +40729,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## mcp_list_tools.completed -当某个条目的 MCP 工具列表已完成时返回。 +当针对某个条目列出 MCP 工具的操作已完成时返回。 ### Schema -架构名称： `RealtimeServerEventMCPListToolsCompleted` +Schema 名称： `RealtimeServerEventMCPListToolsCompleted` ```json { @@ -40825,7 +40825,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40837,11 +40837,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## mcp_list_tools.failed -当列出某个条目的 MCP 工具失败时返回。 +当为某个项目列出 MCP 工具失败时返回。 ### Schema -架构名称： `RealtimeServerEventMCPListToolsFailed` +Schema 名称： `RealtimeServerEventMCPListToolsFailed` ```json { @@ -40933,7 +40933,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -40949,7 +40949,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ### Schema -架构名称： `RealtimeServerEventResponseMCPCallArgumentsDelta` +Schema 名称： `RealtimeServerEventResponseMCPCallArgumentsDelta` ```json { @@ -41113,7 +41113,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -41128,11 +41128,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.mcp_call_arguments.done -在响应生成期间 MCP 工具调用参数最终确定时返回。 +在响应生成期间，当 MCP 工具调用参数最终确定时返回。 ### Schema -架构名称： `RealtimeServerEventResponseMCPCallArgumentsDone` +Schema 名称： `RealtimeServerEventResponseMCPCallArgumentsDone` ```json { @@ -41278,7 +41278,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -41293,11 +41293,11 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ## response.mcp_call.in_progress -当 MCP 工具调用已开始且正在进行时返回。 +在 MCP 工具调用已开始且正在进行时返回。 ### Schema -架构名称： `RealtimeServerEventResponseMCPCallInProgress` +Schema 名称： `RealtimeServerEventResponseMCPCallInProgress` ```json { @@ -41407,7 +41407,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -41424,7 +41424,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ### Schema -架构名称： `RealtimeServerEventResponseMCPCallCompleted` +Schema 名称： `RealtimeServerEventResponseMCPCallCompleted` ```json { @@ -41534,7 +41534,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { @@ -41551,7 +41551,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 ### Schema -架构名称： `RealtimeServerEventResponseMCPCallFailed` +Schema 名称： `RealtimeServerEventResponseMCPCallFailed` ```json { @@ -41661,7 +41661,7 @@ Response 对象将包含响应中的所有输出项，但会省略原始音频 } ``` -### 示例 +### Example ```json { diff --git a/docs/zh/api/reference/resources/realtime/subresources/calls/methods/accept.md b/docs/zh/api/reference/resources/realtime/subresources/calls/methods/accept.md index 9f348fd..058f157 100644 --- a/docs/zh/api/reference/resources/realtime/subresources/calls/methods/accept.md +++ b/docs/zh/api/reference/resources/realtime/subresources/calls/methods/accept.md @@ -1,11 +1,11 @@ -> 有关完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 获取。 +> 完整文档索引请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 末尾添加以下内容获取 Markdown 版本的文档页： `.md` 到页面 URL。 -## 接受调用 +## 接受呼叫 **post** `/realtime/calls/{call_id}/accept` -接收入站 SIP 呼叫并配置将 -处理它。 +接听来电 SIP 呼叫并配置将用于处理该呼叫的实时会话。 +处理该呼叫。 ### 路径参数 @@ -15,7 +15,7 @@ - `type: "realtime"` - 要创建的会话类型。始终 `realtime` 用于 Realtime API。 + 要创建的会话类型。始终为 `realtime` ，用于 Realtime API。 - `"realtime"` @@ -35,13 +35,13 @@ - `rate: optional 24000` - 音频的采样率。始终 `24000`. + 音频的采样率。始终为 `24000`. - `24000` - `type: optional "audio/pcm"` - 音频格式。始终 `audio/pcm`. + 音频格式。始终为 `audio/pcm`. - `"audio/pcm"` @@ -51,7 +51,7 @@ - `type: optional "audio/pcmu"` - 音频格式。始终 `audio/pcmu`. + 音频格式。始终为 `audio/pcmu`. - `"audio/pcmu"` @@ -61,19 +61,19 @@ - `type: optional "audio/pcma"` - 音频格式。始终 `audio/pcma`. + 音频格式。始终为 `audio/pcma`. - `"audio/pcma"` - `noise_reduction: optional object { type }` - 输入音频降噪的配置。可以设置为 `null` 以关闭。 - 降噪会在音频被发送到 VAD 和模型之前，过滤添加到输入音频缓冲区中的音频。 - 过滤音频可以通过改善对输入音频的感知，提高 VAD 和轮流检测的准确性（减少误报）以及模型性能。 + 输入音频降噪的配置。可设置为 `null` 以关闭。 + 降噪会在输入音频发送到 VAD 和模型之前，对添加到输入音频缓冲区中的音频进行过滤。 + 对音频进行过滤可以通过改善对输入音频的感知，提高 VAD 和 turn 检测的准确率（减少误报），并提升模型性能。 - `type: optional NoiseReductionType` - 降噪的类型。 `near_field` 适用于近讲麦克风，如耳机， `far_field` 适用于远场麦克风，如笔记本电脑或会议室麦克风。 + 降噪类型。 `near_field` 适用于耳机等近场麦克风， `far_field` 适用于笔记本或会议室麦克风等远场麦克风。 - `"near_field"` @@ -81,13 +81,13 @@ - `transcription: optional AudioTranscription` - 输入音频转录的配置，默认为关闭，可以设置为 `null` 以在开启后关闭。输入音频转录并非模型的原生功能，因为模型直接消费音频。转录通过 [the /audio/transcriptions endpoint](/docs/api-reference/audio/createTranscription) 异步运行，应视为对输入音频内容的指导，而非模型实际听到的内容。客户端可以选择性地设置转录的语言和提示词，这些为转录服务提供额外的指导。 + 输入音频转录的配置，默认为关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为对输入音频内容的指引，而非模型实际听到内容的精确记录。客户端可以可选地设置转录的语言和提示，以为转录服务提供额外的指引。 - `delay: optional "minimal" or "low" or "medium" or 2 more` - 控制模型在输出转录文本前等待的时间。 - 较高的值可以提高转录准确性，但会增加延迟。 - 仅在 `gpt-realtime-whisper` 的正式版 Realtime 会话中支持。 + 控制模型在输出转写文本前等待多长时间。 + 较高的值可以提高转写准确率，但会增加延迟。 + 仅在以下场景中支持： `gpt-realtime-whisper` （GA 实时会话中）。 - `"minimal"` @@ -101,27 +101,27 @@ - `keywords: optional array of string` - 用于指导输入音频转录的词语或短语。支持者： `gpt-transcribe` 和 `gpt-live-transcribe`. + 用于引导输入音频转写的词语或短语。支持以下模型： `gpt-transcribe` 和 `gpt-live-transcribe`. - `language: optional string` - 输入音频的语言。在 - [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) （例如。 `en`）格式中提供输入语言 - 将提高准确性和降低延迟。 + 输入音频的语言。在以下字段中提供输入语言： + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) （例如。 `en`）格式 + 可提高准确率和降低延迟。 - `languages: optional array of string` - 输入音频的可能语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式提供。支持者： `gpt-transcribe` 和 `gpt-live-transcribe`. + 输入音频可能的语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。支持以下模型： `gpt-transcribe` 和 `gpt-live-transcribe`. - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。当需要带说话人标签的说话人分离时，请使用 `gpt-4o-transcribe-diarize` 。 + 用于转写的模型。当前可选项包括 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。在需要带说话者标签的说话人分离时，请使用 `gpt-4o-transcribe-diarize` 。 - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。当需要带说话人标签的说话人分离时，请使用 `gpt-4o-transcribe-diarize` 。 + 用于转写的模型。当前可选项包括 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。在需要带说话者标签的说话人分离时，请使用 `gpt-4o-transcribe-diarize` 。 - `"whisper-1"` @@ -141,94 +141,94 @@ - `prompt: optional string` - 可选文本，用于指导模型的风格或延续先前的音频 + 用于引导模型风格的可选文本，或用于延续上一段音频 片段。 - 对于 `whisper-1`，则 [提示词是关键字列表](/docs/guides/speech-to-text#prompting). - 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），提示词是自由文本字符串，例如“期望与科技相关的词语”。 - 提示词不支持与 `gpt-realtime-whisper` 的正式版 Realtime 会话中支持。 + 对于 `whisper-1`，则 [prompt 是关键词列表](/docs/guides/speech-to-text#prompting). + 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），prompt 是一段自由文本字符串，例如“expect words related to technology”。 + Prompt 在以下模型中不受支持： `gpt-realtime-whisper` （GA 实时会话中）。 - `turn_detection: optional RealtimeAudioInputTurnDetection or null` - 轮流检测配置，可以是Server VAD或Semantic VAD。可以设置为 `null` 以关闭，在这种情况下，客户端必须手动触发模型响应。 + 轮次检测的配置，可以是 Server VAD 或 Semantic VAD。可将其设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 - Server VAD意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时作出响应。 + Server VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - Semantic VAD更高级，使用轮流检测模型（结合VAD）语义估算用户是否已经说完，然后根据该概率动态设置超时时间。例如，如果用户音频以“嗯”淡出，模型将评分出较低的轮流结束概率，并等待更长时间让用户继续说话。这对于更自然的对话很有用，但可能会产生更高的延迟。 + Semantic VAD 更为先进，它使用一个轮次检测模型（与 VAD 配合使用）从语义上估计用户是否已经说完，然后根据该概率动态设置超时时间。例如，如果用户音频以“嗯……”这种声音拖尾，模型会给出一个较低的轮次结束概率，并等待更长时间让用户继续说话。这对于更自然的对话非常有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转录会话中，轮流检测必须 - 设置为 `null`；不支持VAD。 + 对于 `gpt-realtime-whisper` 转写会话中，轮次检测必须设置为 + 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），检测到用户语音时开启，静默一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 轮流检测类型， `server_vad` 以开启简单的Server VAD。 + 轮次检测的类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在VAD停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已经在响应，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，当模型已经在响应时，此设置可能会导致响应创建失败。 - 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果同时将 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选超时，超时后将自动触发模型响应。这在 - 用户长时间停顿出乎意料的情况下非常有用，例如电话 - 通话。模型将有效地提示用户根据 + 可选的超时时间，超过该时间后将自动触发模型响应。这在 + 例如电话通话等用户长时间停顿属于异常情况的场景下非常有用。模型会根据 + 当前上下文有效地提示用户继续对话。 当前上下文继续对话。 - 超时值将在最后一个模型响应的音频播放完毕后应用， - 即设置为 `response.done` 时间加上音频播放时长。 + 超时值将在最后一个模型响应的音频播放结束后开始计时， + 即设置为该 `response.done` 时间加上音频播放时长。 - 一个 `input_audio_buffer.timeout_triggered` 事件（以及 - 与响应关联的事件）将在达到超时时发出。 + 一个 `input_audio_buffer.timeout_triggered` 事件（以及与 Response 关联的事件） + 将在达到超时时被发出。 空闲超时目前仅支持 `server_vad` 模式。 - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断（取消）任何正在进行的、输出到默认 - 对话（即。 `conversation` 的 `auto`）的响应。如果 `true` 则响应将被取消，否则将继续直到完成。 + 当 VAD start 事件发生时，是否自动中断（取消）任何正在向默认 + 对话（即。 `conversation` 的 `auto`）输出响应的进行中响应。如果为 `true` 则该响应将被取消，否则将一直持续到完成。 - 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果同时将 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。VAD 检测到语音前要包含的音频量（以 - 毫秒）。默认为 300 毫秒。 + 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 + 毫秒）。默认为 300ms。 - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。用于检测语音停止的静音持续时间（毫秒）。默认值 - 为 500 毫秒。使用较短的值时，模型响应会更快， - 但可能会在用户的短暂停顿时打断。 + 仅用于 `server_vad` 模式。用于检测语音停止的静默时长（以毫秒为单位）。默认为 + 500ms。该值越小，模型响应越快， + 但可能会在用户的短暂停顿中插话。 - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。 - 更高的阈值需要更响亮的音频才能激活模型， + 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。较 + 高的阈值要求更大的音频音量才能激活模型， 因此在嘈杂环境中可能表现更好。 - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义轮次检测，使用模型来确定用户何时说完话。 + 服务端语义轮次检测，通过模型来判断用户何时结束说话。 - `type: "semantic_vad"` - 轮流检测类型， `semantic_vad` 以开启语义 VAD。 + 轮次检测的类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` - `create_response: optional boolean` - 是否在发生 VAD 停止事件时自动生成响应。 + 是否在 VAD 停止事件发生时自动生成响应。 - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户更长时间继续说话， `high` 会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + 仅用于 `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续说话， `high` 会更快地响应。 `auto` 为默认值，等同于 `medium`. `low`, `medium`，以及 `high` 分别具有 8s、4s 和 2s 的最大超时时间。 - `"low"` @@ -240,8 +240,8 @@ - `interrupt_response: optional boolean` - 是否自动中断任何正在进行的自动输出响应 - 对话（即。 `conversation` 的 `auto`）当 VAD 起始事件发生时。 + 是否在发生 VAD 开始事件时，自动使用输出到默认 + 对话（即。 `conversation` 的 `auto`) 来中断任何进行中的响应。 - `output: optional RealtimeAudioConfigOutput` @@ -251,20 +251,20 @@ - `speed: optional number` - 模型口头响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。该值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型语音响应速度相对于原始速度的倍数。 + 1.0 是默认速度。0.25 是最低速度。1.5 是最高速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 - 此参数是对生成的音频进行的后处理调整， - 也可以提示模型说得更快或更慢。 + 该参数是对生成后音频的后处理调整，也可以 + 通过提示模型说得更快或更慢来实现。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more or object { id }` - 模型用于响应的语音。支持的内置语音为 + 模型用于回应的语音。支持的内置语音为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, - `marin`，以及 `cedar`。你也可以提供自定义语音对象，包含 - 一个 `id`，例如 `{ "id": "voice_1234" }`。一旦模型至少响应过一次音频， - 在会话期间就无法更改语音。 - 我们建议 `marin` 和 `cedar` 以获得最佳质量。 + `marin`，以及 `cedar`。你也可以提供一个自定义语音对象，例如 + 一个 `id`，例如 `{ "id": "voice_1234" }`。一旦模型至少 + 响应过一次音频，会话期间就无法更改语音。 + 我们推荐 `marin` 和 `cedar` 以获得最佳质量。 - `string` @@ -292,7 +292,7 @@ - `ID object { id }` - 自定义语音参考。 + 自定义语音引用。 - `id: string` @@ -300,24 +300,24 @@ - `include: optional array of "item.input_audio_transcription.logprobs"` - 服务器输出中要包含的其他字段。 + 需要在服务端输出中包含的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`：为输入音频转写包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 预先附加到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型产生期望的响应。可以指示模型关于响应内容和格式（例如“极其简洁”、“表现得友好”、“以下是一些良好响应的示例”）以及音频行为（例如“说得快些”、“为你的声音注入情感”、“经常大笑”）。模型不保证会遵循这些指令，但它们为模型提供了期望行为的指导。 + 预置于模型调用之前的默认系统指令（即系统消息）。该字段允许客户端引导模型生成期望的响应。可以指示模型在响应内容和格式上（例如"保持非常简洁"、"表现得友好一些"、"以下是较好的响应示例"）以及音频行为上（例如"说话快一些"、"在语音中加入情感"、"经常笑"）的偏好。这些指令不保证被模型严格遵循，但为模型期望的行为提供了引导。 - 请注意，服务器会设置默认指令，如果未设置此字段，将使用这些默认指令，并且在 `session.created` 会话开始时会显示在事件中。 + 请注意，服务端会设置默认指令，在该字段未设置时使用，并且在会话开始时的 `session.created` 事件中可见。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供一个介于 1 到 4096 之间的整数以 - 限制输出 token，或 `inf` 对于特定模型可用的最大 token 数。默认值 - 为 `inf`. + 单次助手响应的最大输出 token 数， + 包含工具调用。请提供一个介于 1 到 4096 之间的整数以 + 限制输出 token 数，或 `inf` 表示给定模型可用的最大 token 数。默认为 + 给定模型。默认为 `inf`. - `number` @@ -327,13 +327,13 @@ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 本会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 本会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -376,8 +376,8 @@ - `output_modalities: optional array of "text" or "audio"` 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将以音频加转录文本的形式响应。 `["text"]` 可用于使 - 模型仅以文本形式响应。无法同时请求 `text` 和 `audio` 。 + 模型将以音频加上文字转录的方式进行响应。 `["text"]` 可用于让 + 模型仅以文本形式进行响应。不能同时请求 `text` 和 `audio` 两者。 - `"text"` @@ -385,8 +385,8 @@ - `parallel_tool_calls: optional boolean` - 模型是否可以并行调用多个工具。仅受 - 推理 Realtime 模型支持，例如 `gpt-realtime-2`. + 模型是否可以并行调用多个工具。仅 + 推理型 Realtime 模型支持，例如 `gpt-realtime-2`. - `prompt: optional ResponsePrompt or null` @@ -399,19 +399,19 @@ - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选映射，用于替换你的 - 提示中的变量。替换值可以是字符串，或其他 - Response 输入类型，如图像或文件。 + 在提示中用于替换变量的可选值映射。 + 替换值可以是字符串，也可以是其他 + Response 输入类型，例如图片或文件。 - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 传递给模型的文本输入。 - `text: string` - 模型的文本输入。 + 传递给模型的文本输入。 - `type: "input_text"` @@ -421,7 +421,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示词前缀的确切结尾。断点从其所属请求继承 TTL。 `prompt_cache_options.ttl`；该边界不按 token 块取整。 + 标记可复用提示前缀的精确结束位置。该断点继承请求中的 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -431,11 +431,11 @@ - `ResponseInputImage object { detail, type, file_id, 2 more }` - 发送给模型的图像输入。了解 [图像输入](/docs/guides/vision). + 发送到模型的图像输入。了解 [图像输入](/docs/guides/vision). - `detail: ImageDetail` - 发送给模型的图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。默认为 `auto`. + 发送到模型的图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。默认为 `auto`. - `"low"` @@ -453,15 +453,15 @@ - `file_id: optional string or null` - 发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `image_url: optional string or null` - 发送给模型的图像的 URL。可以是完整限定的 URL，也可以是 data URL 中 base64 编码的图像。 + 要发送到模型的图像的 URL。可以是完全限定的 URL，也可以是 data URL 中 base64 编码的图像。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示词前缀的确切结尾。断点从其所属请求继承 TTL。 `prompt_cache_options.ttl`；该边界不按 token 块取整。 + 标记可复用提示前缀的精确结束位置。该断点继承请求中的 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -471,7 +471,7 @@ - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 发送到模型的文件输入。 - `type: "input_file"` @@ -481,7 +481,7 @@ - `detail: optional "auto" or "low" or "high"` - 发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本模型， `auto` 使用高质量渲染，可能会增加输入 token 使用量。使用 `low` 以降低渲染成本，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 要发送到模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 使用量。使用 `low` 进行低成本渲染，或 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -491,23 +491,23 @@ - `file_data: optional string` - 发送给模型的文件的内容。 + 要发送到模型的文件内容。 - `file_id: optional string or null` - 发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `file_url: optional string` - 发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示词前缀的确切结尾。断点从其所属请求继承 TTL。 `prompt_cache_options.ttl`；该边界不按 token 块取整。 + 标记可复用提示前缀的精确结束位置。该断点继承请求中的 TTL `prompt_cache_options.ttl`；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -517,15 +517,15 @@ - `version: optional string or null` - 提示词模板的可选版本。 + 提示模板的可选版本。 - `reasoning: optional RealtimeReasoning` - 支持推理的 Realtime 模型（例如）的配置 `gpt-realtime-2`. + 针对支持推理的 Realtime 模型（如 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 对支持推理的 Realtime 模型（例如）进行推理时的努力程度约束 + 针对支持推理的 Realtime 模型（如 `gpt-realtime-2`. - `"minimal"` @@ -540,17 +540,17 @@ - `tool_choice: optional RealtimeToolChoiceConfig` - 模型如何选择工具。提供字符串模式之一，或强制指定某个 - 函数/MCP 工具。 + 模型选择工具的方式。提供字符串模式之一，或强制使用特定 + function/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型调用哪个（如果有）工具。 + 控制模型调用哪些工具（若有）。 `none` 表示模型不会调用任何工具，而是生成一条消息。 - `auto` 表示模型可以选择生成消息或调用一个或多个 - 工具。 + `auto` 表示模型可以在生成消息或调用一个或 + 多个工具之间进行选择。 `required` 表示模型必须调用一个或多个工具。 @@ -562,11 +562,11 @@ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定的函数。 + 使用此选项可强制模型调用特定的函数。 - `name: string` - 要调用的函数的名称。 + 要调用的函数名称。 - `type: "function"` @@ -576,7 +576,7 @@ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可强制模型调用远程 MCP 服务器上的特定工具。 - `server_label: string` @@ -590,7 +590,7 @@ - `name: optional string or null` - 要在服务器上调用的工具的名称。 + 要在服务器上调用的工具名称。 - `tools: optional RealtimeToolsConfig` @@ -601,8 +601,8 @@ - `description: optional string` 函数的描述，包括何时以及如何 - 调用它的指导，以及在调用时应该告知用户什么 - （如果有）的指导。 + 调用它的指引，以及调用时 + （应告知用户的内容（如果有）。 - `name: optional string` @@ -610,7 +610,7 @@ - `parameters: optional unknown` - 函数在 JSON Schema 中的参数。 + 以 JSON Schema 表示的函数参数。 - `type: optional "function"` @@ -620,16 +620,16 @@ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程 Model Context Protocol - (MCP) 服务器为模型提供额外工具的访问权限。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol（MCP）服务器为模型提供对额外工具的访问 + 。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). - `server_label: string` - 该 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中标识它。 - `type: "mcp"` - MCP 工具的类型。始终为 `mcp`. + MCP 工具的类型，恒为 `mcp`. - `"mcp"` @@ -643,48 +643,48 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许使用的工具名称的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用的工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器被 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - ，它将匹配此过滤器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此过滤器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，无论是 - 使用自定义 MCP 服务器 URL 还是服务连接器。你的应用程序 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可用于远程 MCP 服务器的 OAuth 访问令牌，既可以 + 与自定义 MCP 服务器 URL 一起使用，也可以与服务连接器一起使用。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，类似于 ChatGPT 中可用的那些。 - `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的那些连接器。其值必须为以下之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多信息 + 关于服务连接器 [请参见此处](/docs/guides/tools-remote-mcp#connectors). - 当前支持 `connector_id` 的值为： + 目前支持的值 `connector_id` 如下： - - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮箱： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -704,56 +704,56 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否被延迟，并通过工具搜索发现。 - `headers: optional map[string] or null` - 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 发送到 MCP 服务器的可选 HTTP 头。用于身份验证 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器的哪些工具需要批准。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与工具关联的筛选器对象 - 需要批准。 + 指定 MCP 服务器的哪些工具需要批准。可以为 + `always`, `never`，也可以是与工具关联的过滤对象 + 需要审批。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用的工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器被 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - ，它将匹配此过滤器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此过滤器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用的工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器被 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - ，它将匹配此过滤器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [标记为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此过滤器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一批准策略。选项之一为 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要批准。当 - 设置为 `never`，时，所有工具都不需要批准。 + 为所有工具指定单一审批策略。可选值为 `always` 或 + `never`。当设置为 `always`，时，所有工具都需要审批。当 + 设置为 `never`，时，所有工具都不需要审批。 - `"always"` @@ -765,60 +765,60 @@ - `server_url: optional string` - MCP 服务器的 URL。选项之一为 `server_url`, `connector_id`，或 - `tunnel_id` 必须提供。 + MCP 服务器的 URL。可选值为 `server_url`, `connector_id`，或 + `tunnel_id` 必须提供其中一个。 - `tunnel_id: optional string` - 安全 MCP 隧道 ID，用于替代直接服务器 URL。选项之一为 - `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 + 要使用的安全 MCP 隧道 ID，用于替代直接的服务器 URL。可选值为 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供其中一个。 - `tracing: optional RealtimeTracingConfig or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用了 追踪，则无法修改该配置。 + Realtime API 可以将会话追踪写入到 [Traces Dashboard](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用追踪。一旦 + 为会话启用了追踪，就无法再修改该配置。 - `auto` 将使用 追踪 为会话创建追踪，并为 - 工作流 名称、组 ID 和元数据设置默认值。 + `auto` 将为该会话创建一个使用默认值的追踪，包括默认的 + 工作流名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. + 启用追踪并为追踪配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 用于 追踪 的精细配置。 + 对追踪的细粒度配置。 - `group_id: optional string` - 要附加到此 追踪 的组 ID，用于启用筛选和 - 在追踪仪表盘中进行分组。 + 附加到此追踪的 group id，用于在 Traces Dashboard 中进行筛选和 + 分组。 - `metadata: optional unknown` - 要附加到此追踪的任意元数据，以便在追踪仪表板中启用 - 过滤。 + 要附加到该追踪的任意元数据，用于启用 + 在 Traces Dashboard 中进行过滤。 - `workflow_name: optional string` - 要附加到此工作流的追踪名称。此名称用于在追踪仪表板中 - 对该追踪进行命名。 + 要附加到该工作流的追踪的名称。用于 + 在 Traces Dashboard 中命名追踪。 - `truncation: optional RealtimeTruncation` - 当对话中的 token 数量超过模型的输入 token 限制时，对话将被截断，这意味着消息（从最早的开始）将不会包含在模型的上下文中。一个 32k 上下文的模型，若最大输出 token 为 4,096，则在发生截断前，上下文中只能包含 28,224 个 token。 + 当对话中的 token 数量超过模型的输入 token 上限时，对话将被截断，这意味着最早的消息将不会包含在模型的上下文中。一个 32k 上下文、最大输出 4,096 token 的模型，在截断发生前上下文中只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大 token 限制进行截断，这是控制 token 使用量和成本的有效方式。 + 客户端可以配置截断行为，以较低的 token 上限进行截断，这是控制 token 使用量和成本的有效方法。 - 截断将减少下一轮中的缓存 token 数量（破坏缓存），因为消息会从上下文的开头被丢弃。然而，客户端也可以配置截断以保留最多达到最大上下文大小一定比例的消息，这将减少未来截断的需求，从而提高缓存命中率。 + 由于消息从上下文开头被丢弃，截断会减少下一轮中缓存的 token 数量（破坏缓存）。不过，客户端也可以将截断配置为保留最大上下文大小一定比例的消息，从而减少未来截断的需要，进而提高缓存命中率。 - 截断可以完全禁用，这意味着服务器将永远不会截断，而是在对话超过模型的输入 token 限制时返回错误。 + 可以完全禁用截断，这意味着服务端永远不会截断，但如果对话超过模型的输入 token 上限，将改为返回错误。 - `"auto" or "disabled"` - 会话使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 将禁用截断，并在对话超过输入 token 限制时发出错误。 + 用于该会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将禁用截断，并在对话超过输入 token 上限时返回错误。 - `"auto"` @@ -826,11 +826,11 @@ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入 token 限制时，保留对话 token 的一部分。这允许你将截断分摊到多个轮次，有助于改善缓存 token 的使用。 + 当对话超过输入 token 上限时，保留一定比例的对话 token。这允许你在多轮之间分摊截断开销，有助于提升缓存 token 的使用率。 - `retention_ratio: number` - 当对话超过输入 token 限制时要保留的指令后对话 token 的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着将丢弃消息，直到使用的 token 达到最大允许 token 的 80%。这有助于降低截断频率并提升缓存命中率。 + 超过输入 token 上限时保留的指令后对话 token 比例（`0.0` - `1.0`）。当对话超过输入 token 上限时，保留该比例的对话 token。将其设置为 `0.8` 意味着会丢弃消息，直到剩余 token 使用量达到最大允许 token 的 80%。这有助于降低截断频率并提高缓存命中率。 - `type: "retention_ratio"` @@ -840,11 +840,11 @@ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义 token 限制。如果未提供，将使用模型的默认 token 限制。 + 此截断策略的可选自定义 token 上限。如果未提供，将使用模型默认的 token 上限。 - `post_instructions: optional number` - 指令（包括工具定义）后对话中允许的最大 token 数。例如，将其设置为 5,000 意味着当对话在指令后超过 5,000 个 token 时会发生截断。此值不能高于模型的上下文窗口大小减去最大输出 token 数。 + 指令之后（即包含工具定义）对话中允许的最大 token 数。例如，将其设置为 5,000 表示当指令之后的对话超过 5,000 token 时将发生截断。该值不能高于模型上下文窗口大小减去最大输出 token 数。 ### 示例 diff --git a/docs/zh/api/reference/resources/realtime/subresources/client_secrets.md b/docs/zh/api/reference/resources/realtime/subresources/client_secrets.md index 555a039..3b7a410 100644 --- a/docs/zh/api/reference/resources/realtime/subresources/client_secrets.md +++ b/docs/zh/api/reference/resources/realtime/subresources/client_secrets.md @@ -1,48 +1,48 @@ # 客户端密钥 -> 有关完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后附加 `.md` 来获取。 +> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾追加 `.md` 即可获取该页面的 Markdown 版本。 ## 创建客户端密钥 **post** `/realtime/client_secrets` -创建带有关联会话配置的 Realtime 客户端密钥。 +创建一个 Realtime 客户端密钥，并附带会话配置。 -客户端密钥是短期令牌，可以传递给客户端应用， -例如 Web 前端或移动客户端，从而无需泄露你的主 API 密钥即可授予对 Realtime API 的访问权限。 +客户端密钥是短时令牌，可以传递给客户端应用， +例如 Web 前端或移动端客户端，授予其访问 Realtime API 的权限，且不会泄露你的主 API 密钥。 你可以为每个客户端密钥配置自定义 TTL。 -你还可以将会话配置选项附加到客户端密钥，这些选项将 -应用于使用该客户端密钥创建的任何会话，但也可以被 +你也可以将会话配置选项附加到客户端密钥，这些选项将 +应用于使用该客户端密钥创建的所有会话，但这些选项也会被 客户端连接覆盖。 -[了解有关通过 WebRTC 使用客户端密钥进行身份验证的更多信息](/docs/guides/realtime-webrtc). +[了解如何通过 WebRTC 使用客户端密钥进行身份验证](/docs/guides/realtime-webrtc). -返回创建的客户端密钥和有效的会话对象。客户端密钥是一个字符串，看起来像 `ek_1234`. +返回创建的客户端密钥以及生效后的会话对象。客户端密钥是一个字符串，格式类似 `ek_1234`. ### 请求体参数 - `expires_after: optional object { anchor, seconds }` - 客户端密钥过期的配置。过期是指在此时间之后 - 客户端密钥将不再有效用于创建会话。会话本身可能 - 在开始后继续运行。一个密钥可用于创建多个会话， - 直到过期为止。 + 客户端密钥过期的配置。“过期”是指之后的时间 + 客户端密钥将不再有效，无法用于创建会话。已开始的会话本身可能会 + 在该时间之后继续运行。密钥在过期前可用于创建多个会话 + 直到过期。 - `anchor: optional "created_at"` - 客户端密钥过期的锚点，即 `seconds` 将被添加到 `created_at` 客户端密钥的时间以生成过期时间戳。目前仅支持 `created_at` 。 + 客户端密钥过期的基准点，即 `seconds` 将添加到客户端密钥的 `created_at` 时间以生成过期时间戳。目前仅支持 `created_at` 。 - `"created_at"` - `seconds: optional number` - 从锚点到过期的秒数。选择一个介于 `10` 和 `7200` （2小时）之间的值。如果未指定，默认为600秒（10分钟）。 + 从基准点到过期时间的秒数。选择一个介于 `10` 和 `7200` （2 小时）之间的值。如果未指定，默认值为 600 秒（10 分钟）。 - `session: optional RealtimeSessionCreateRequest or RealtimeTranscriptionSessionCreateRequest` - 客户端密钥使用的会话配置。选择实时 - 会话或转录会话。 + 用于客户端密钥的会话配置。选择实时 + 会话或转写会话。 - `RealtimeSessionCreateRequest object { type, audio, include, 11 more }` @@ -50,7 +50,7 @@ - `type: "realtime"` - 要创建的会话类型。对于实时API始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -102,13 +102,13 @@ - `noise_reduction: optional object { type }` - 输入音频噪声抑制的配置。可设置为 `null` 以关闭。 - 噪声抑制会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提高模型性能。 + 输入音频降噪配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行处理。 + 对音频进行过滤可以通过改善对输入音频的感知，从而提高 VAD 和打断检测的准确率（减少误报），并提升模型表现。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `"near_field"` @@ -116,13 +116,13 @@ - `transcription: optional AudioTranscription` - 输入音频转录的配置，默认关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应视为输入音频内容的指导，而非模型所听到内容的精确反映。客户端可以选择设置转录的语言和提示，这些为转录服务提供额外指导。 + 输入音频转写配置，默认为关闭状态，可设置为 `null` 以在启用后关闭。输入音频转写并非模型原生功能，因为模型直接消费音频。转写通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的指引，而非模型实际听到的精确内容。客户端可以可选地设置转写所用的语言和提示词，这些为转写服务提供了额外的指引。 - `delay: optional "minimal" or "low" or "medium" or 2 more` - 控制模型在发出转录文本之前等待的时间。 - 较高的值可以提高转录准确性，但会增加延迟。 - 仅在 GA Realtime 会话中支持 `gpt-realtime-whisper` 。 + 控制模型在输出转写文本之前等待的时间。 + 较高的值可以提高转写准确率，但会增加延迟。 + 仅在 `gpt-realtime-whisper` 在 GA Realtime 会话中受支持。 - `"minimal"` @@ -136,27 +136,27 @@ - `keywords: optional array of string` - 用于指导输入音频转录的词语或短语。支持 `gpt-transcribe` 和 `gpt-live-transcribe`. + 用于引导输入音频转写的词语或短语。支持 `gpt-transcribe` 和 `gpt-live-transcribe`. - `language: optional string` 输入音频的语言。在 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) （例如。 `en`）格式 - 将提高准确性和延迟。 + 可提升准确率并降低延迟。 - `languages: optional array of string` - 输入音频的可能语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。支持 `gpt-transcribe` 和 `gpt-live-transcribe`. + 输入音频可能的语言，格式为 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。支持模型： `gpt-transcribe` 和 `gpt-live-transcribe`. - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`。当需要带说话人标签的说话人分离时，使用 `gpt-4o-transcribe-diarize` 。 + 用于转录的模型。当前可选值有 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。在需要 `gpt-4o-transcribe-diarize` 并附带说话人标签的说话人分离时使用。 - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`。当需要带说话人标签的说话人分离时，使用 `gpt-4o-transcribe-diarize` 。 + 用于转录的模型。当前可选值有 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。在需要 `gpt-4o-transcribe-diarize` 并附带说话人标签的说话人分离时使用。 - `"whisper-1"` @@ -176,84 +176,84 @@ - `prompt: optional string` - 一个可选文本，用于引导模型的风格或继续之前的音频 + 用于引导模型风格或延续上一段音频的可选文本 片段。 - 对于 `whisper-1`， [提示词是一组关键词列表](/docs/guides/speech-to-text#prompting). - 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），提示词是自由文本字符串，例如“期望与科技相关的词语”。 - 提示词不适用于 `gpt-realtime-whisper` 。 + 对于 `whisper-1`，该 [prompt 是一个关键词列表](/docs/guides/speech-to-text#prompting). + 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），prompt 为一段自由文本，例如“expect words related to technology”。 + 以下模型不支持 prompt： `gpt-realtime-whisper` 在 GA Realtime 会话中受支持。 - `turn_detection: optional RealtimeAudioInputTurnDetection or null` - 用于轮流检测的配置，可以是服务器端 VAD 或语义 VAD。可设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可选 Server VAD 或 Semantic VAD。可设置为 `null` 以关闭该功能，此时客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将基于音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型会基于音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更为高级，它使用话轮检测模型（结合 VAD）从语义上估计用户是否已经说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”逐渐减弱，模型会给出较低的话轮结束概率，并等待更长时间让用户继续说话。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更先进，它会结合 VAD 使用一个轮次判断模型来语义层面估计用户是否已说完，然后基于该概率动态设置一个超时时间。例如，如果用户的语音以“嗯……”之类的语气词收尾，模型会给出一个较低的轮次结束概率，并等待更长时间以便用户继续说话。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转写会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` transcription 会话中，turn detection 必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静音一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以开启简单的服务端 VAD。 + turn detection 类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，在模型已经正在响应时可能会无法创建响应。 - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选的超时时间，超过该时间后将自动触发模型响应。这 - 对于用户长时间停顿属于意外情况时很有用，例如电话 - 通话。模型将基于当前上下文有效地提示用户继续对话。 - 基于当前上下文。 + 可选超时时间，到达后将自动触发一次响应。 + 这在用户长时间停顿出乎意料的情况下很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话。 + 于当前上下文。 - 超时时间将在最后一个模型响应的音频播放完毕后开始计算， - 即它设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在最后一次模型响应的音频播放结束后应用， + 即它被设置为 `response.done` time plus audio playback duration. - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 达到超时时间时将发出与响应关联的事件）。 - 空闲超时目前仅支持 `server_vad` 模式。 + 一个 `input_audio_buffer.timeout_triggered` event (plus events + associated with the Response) will be emitted when the timeout is reached. + Idle timeout is currently only supported for `server_vad` mode. - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断（取消）任何正在进行的、具有输出到默认 - 对话（即。 `conversation` 的 `auto`）响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + Whether or not to automatically interrupt (cancel) any ongoing response with output to the default + conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete. - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音持续时间（以毫秒为单位）。默认为 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈值越高， - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义转折检测，使用模型来判断用户是否已说完话。 + 服务端语义轮次检测，通过模型判断用户何时已结束发言。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + turn detection 类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` @@ -263,7 +263,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户继续说的时间更长， `high` 则会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`、 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + Used only for `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续发言， `high` 会更快地作出响应。 `auto` 为默认值，相当于 `medium`. `low`, `medium`，以及 `high` 的最大超时分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -275,8 +275,8 @@ - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断任何正在进行的响应并输出到默认的 - 对话（即。 `conversation` 的 `auto`）。 + 当存在输出到默认 + conversation (i.e. `conversation` of `auto`) 时，是否自动中断任何正在进行的响应。 - `output: optional RealtimeAudioConfigOutput` @@ -286,19 +286,19 @@ - `speed: optional number` - 模型语音响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口语化响应的速度，相对于原始速度的倍数。 + 1.0 为默认速度。0.25 为最低速度。1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中修改。 - 此参数是对生成的音频进行后处理调整， - 也可以提示模型说得更快或更慢。 + 此参数是对生成后音频的后处理调整，也 + 可以通过提示让模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more or object { id }` - 模型用于响应的语音。支持的内置语音有 + 模型用于响应的声音。支持的内置声音包括 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, - `marin`、 `cedar`. 你也可以提供带有自定义语音对象 - 一个 `id`, 例如 `{ "id": "voice_1234" }`. 语音无法更改 - 在会话期间，一旦模型至少已响应过一次音频。 + `marin`，以及 `cedar`。你也可以使用 + 一个 `id`，例如 `{ "id": "voice_1234" }`。声音无法更改 + 在会话期间，一旦模型至少响应过一次音频。 我们建议 `marin` 和 `cedar` 以获得最佳质量。 - `string` @@ -335,24 +335,24 @@ - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 预置到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型产生所需响应。可以指导模型响应的内容和格式（例如“极其简洁”、“表现友好”、“以下是良好响应的示例”）以及音频行为（例如“语速快”、“语气注入情感”、“频繁大笑”）。模型不保证遵循这些指令，但指令为模型提供了所需行为的指导。 + 预先添加到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型给出期望的响应。可以指示模型关于响应内容和格式（例如"极其简洁"、"表现得友好"、"以下是良好响应的示例"），以及关于音频行为（例如"快速讲话"、"在声音中注入情感"、"经常笑"）。指令不保证被模型遵循，但它们为模型提供了关于期望行为的指导。 - 请注意，服务器会设置默认指令，如果未设置此字段，将使用这些指令，并且它们会显示在 `session.created` 会话开始处的事件中。 + 请注意，服务端会设置默认指令，如果未设置此字段将使用默认指令，并且这些指令在 `session.created` 事件中于会话开始时可见。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供一个介于 1 到 4096 之间的整数，以 - 限制输出 token，或 `inf` 获取给定模型的最大可用 token 数。默认值为 - 给定模型。默认值为 `inf`. + 单个助手响应的最大输出令牌数， + 包括工具调用。提供介于 1 和 4096 之间的整数以 + 限制输出令牌，或 `inf` 以获取给定模型的可用 + 最大令牌数。默认为 `inf`. - `number` @@ -362,13 +362,13 @@ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -410,9 +410,9 @@ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将响应音频加上转录文本。 `["text"]` 可用于使 - 模型仅以文本形式响应，无法同时请求两者 `text` 和 `audio` 。 + 模型可以响应的模态集合。默认为 `["audio"]`,表示 + 模型将响应音频加文字转录。 `["text"]` 可用于使 + the model respond with text only. It is not possible to request both `text` 和 `audio` at the same time. - `"text"` @@ -420,57 +420,57 @@ - `parallel_tool_calls: optional boolean` - 模型是否可以并行调用多个工具。仅受以下支持 - 推理实时模型，如 `gpt-realtime-2`. + Whether the model may call multiple tools in parallel. Only supported by + reasoning Realtime models such as `gpt-realtime-2`. - `prompt: optional ResponsePrompt or null` - 对提示模板及其变量的引用。 - [了解更多](/docs/guides/text?api-mode=responses#reusable-prompts). + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - 要使用的提示模板的唯一标识符。 + The unique identifier of the prompt template to use. - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选映射，用于替换你 - 提示中的变量。替换值可以是字符串，也可以是其他 - 响应输入类型，如图像或文件。 + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + A text input to the model. - `text: string` - 对模型的文本输入。 + The text input to the model. - `type: "input_text"` - 输入项的类型。始终为 `input_text`. + The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: ImageDetail` - 要发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`, 或 `original`。默认为 `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`。默认为 `auto`. - `"low"` @@ -482,41 +482,41 @@ - `type: "input_image"` - 输入项的类型。始终为 `input_image`. + The type of the input item. Always `input_image`. - `"input_image"` - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，或 data URL 中的 base64 编码图片。 + 发送给模型的图片 URL。可以是完整的 URL，也可以是 base64 编码的图片数据 URL。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的输入文件。 - `type: "input_file"` - 输入项的类型。始终为 `input_file`. + The type of the input item. Always `input_file`. - `"input_file"` - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 发送给模型的文件细节级别。使用 `auto` 可让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 使用量。使用 `low` 可使用较低成本的渲染，或使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -526,41 +526,41 @@ - `file_data: optional string` - 要发送给模型的文件内容。 + 发送给模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `version: optional string or null` - 提示模板的可选版本。 + 可选的提示模板版本。 - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 面向支持推理的 Realtime 模型（例如）的配置 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 对支持推理的 Realtime 模型（例如 + 限制支持推理的 Realtime 模型（例如）的推理力度 `gpt-realtime-2`. - `"minimal"` @@ -575,16 +575,16 @@ - `tool_choice: optional RealtimeToolChoiceConfig` - 模型如何选择工具。提供一种字符串模式，或强制指定某个 - 函数/MCP 工具。 + 模型如何选择工具。提供一个字符串模式，或强制使用特定的 + function/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型是否调用工具以及调用哪个（如果有）工具。 + 控制模型调用哪个工具（如果有的话）。 - `none` 表示模型不会调用任何工具，而是生成一条消息。 + `none` 表示模型将不调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个 + `auto` 表示模型可以在生成消息或调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -597,7 +597,7 @@ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可强制模型调用指定的函数。 - `name: string` @@ -611,7 +611,7 @@ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -635,9 +635,9 @@ - `description: optional string` - 函数的描述，包括调用时机和方式 - 的指导，以及调用时应告知用户什么内容 - （如果有）。 + 函数的说明，包括何时以及如何调用的指导， + 以及调用时向用户说明哪些内容的指导 + （如有）。 - `name: optional string` @@ -645,7 +645,7 @@ - `parameters: optional unknown` - JSON Schema 格式的函数参数。 + 函数的参数，采用 JSON Schema 格式。 - `type: optional "function"` @@ -655,16 +655,16 @@ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供更多工具。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). + 通过远程模型上下文协议 (MCP) 服务器让模型访问额外的工具。 + （了解有关 MCP 的更多信息。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). - `server_label: string` - 该 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中标识它。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -678,48 +678,48 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或筛选器对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许使用的工具名称字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，既可以 - 用于自定义 MCP 服务器 URL，也可以用于服务连接器。你的应用 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可与远程 MCP 服务器配合使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`, 或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。必须提供其中 + `server_url`, `connector_id`, or `tunnel_id` 之一。详细了解 + 服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持的 `connector_id` 值为： + 目前支持 `connector_id` 的值为： - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -739,56 +739,56 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载的工具，并通过工具搜索发现。 - `headers: optional map[string] or null` 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具 - 关联的筛选器对象。 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`,或与工具关联的筛选器对象 + 这些工具需要审批。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当设置为 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -800,60 +800,60 @@ - `server_url: optional string` - MCP 服务器的 URL。以下任一项 `server_url`, `connector_id`, 或 - `tunnel_id` 必须提供。 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`, or + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而不是直接服务器 URL。以下任一项 - `server_url`, `connector_id`, 或 `tunnel_id` 必须提供。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 + `server_url`, `connector_id`, or `tunnel_id` 。 - `tracing: optional RealtimeTracingConfig or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入 [追踪仪表板](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦为会话启用了 追踪，便无法再修改该配置。 + 追踪。 - `auto` 将为会话创建一条 追踪，并使用默认值设置 - 工作流 名称、组 ID 和元数据。 + `auto` 将使用默认值创建一个会话 追踪，包括 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪，并为 追踪 配置选项设置默认值。始终 `auto`. + 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 针对 追踪 的细粒度配置。 + 对 追踪 的细粒度配置。 - `group_id: optional string` - 要附加到此 追踪 的组 ID，用于启用过滤和 - 在追踪仪表盘中进行分组。 + 附加到此 追踪 的 group id，用于在追踪仪表板中进行筛选和 + 分组。 - `metadata: optional unknown` - 要附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的过滤。 + 附加到此 追踪 的任意元数据，用于在追踪仪表板中进行 + 筛选。 - `workflow_name: optional string` - 要附加到此 工作流 的名称。这用于 - 在追踪仪表盘中命名该 追踪。 + 附加到此 追踪 的 工作流 名称。它用于在追踪仪表板中 + 为该 追踪 命名。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数超过模型的输入令牌限制时，对话将被截断，这意味着（从最早的开始）消息将不会包含在模型的上下文中。一个 32k 上下文模型，最大输出令牌数为 4,096，在发生截断前只能包含 28,224 个令牌在上下文中。 + 当对话中的 token 数量超过模型的输入 token 上限时，对话将被截断，这意味着部分消息（从最早的消息开始）将不会包含在模型的上下文中。拥有 32k 上下文、最大输出 token 为 4,096 的模型，在发生截断之前，其上下文中最多只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用量和成本的有效方法。 + 客户端可以配置截断行为，使用更低的最大 token 限制进行截断，这是一种有效控制 token 使用量和成本的方式。 - 截断会减少下一轮中的缓存令牌数（破坏缓存），因为消息会从上下文开头被丢弃。但是，客户端也可以配置截断以保留最多达到最大上下文大小一定比例的消息，这将减少未来截断的需求，从而提高缓存命中率。 + 截断会减少下一轮中缓存的 token 数量（破坏缓存），因为消息会从上下文的开头被丢弃。不过，客户端也可以将截断配置为保留最多占最大上下文大小一定比例的消息，从而减少后续截断的需要，进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会进行截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会进行截断，但如果对话超出模型的输入 token 上限，将改为返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话所使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超出输入 token 上限时报错。 - `"auto"` @@ -861,11 +861,11 @@ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多次轮次中分摊截断，有助于改善缓存令牌的使用。 + 在对话超出输入 token 上限后，保留其中一部分会话 token。这可以让你将截断分摊到多轮对话中，有助于改善缓存 token 的使用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，保留指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的 80%。这有助于减少截断频率并提高缓存率。 + 在对话超出输入 token 上限时，要保留的指令后会话 token 比例（`0.0` - `1.0`）。当对话超出输入 token 上限时，将该值设置为 `0.8` 意味着会丢弃消息，直到使用到最大允许 token 的 80%。这有助于降低截断发生频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -875,11 +875,11 @@ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，将使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后对话中允许的最大令牌数（包括工具定义）。例如，将其设置为 5,000 意味着当对话在指令后超过 5,000 个令牌时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令之后（其中包括工具定义）会话所允许的最大 token 数。例如，将其设置为 5,000 意味着当指令之后的会话超过 5,000 token 时就会发生截断。该值不能高于模型的上下文窗口大小减去最大输出 token 数。 - `RealtimeTranscriptionSessionCreateRequest object { type, audio, include }` @@ -887,7 +887,7 @@ - `type: "transcription"` - 要创建的会话类型。对于实时API始终为 `transcription` 用于转录会话的。 + 要创建的会话类型。对于 Realtime API，始终为 `transcription` 用于转录会话。 - `"transcription"` @@ -903,90 +903,90 @@ - `noise_reduction: optional object { type }` - 输入音频噪声抑制的配置。可设置为 `null` 以关闭。 - 噪声抑制会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提高模型性能。 + 输入音频降噪配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行处理。 + 对音频进行过滤可以通过改善对输入音频的感知，从而提高 VAD 和打断检测的准确率（减少误报），并提升模型表现。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `transcription: optional AudioTranscription` - 输入音频转录的配置，默认关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应视为输入音频内容的指导，而非模型所听到内容的精确反映。客户端可以选择设置转录的语言和提示，这些为转录服务提供额外指导。 + 输入音频转写配置，默认为关闭状态，可设置为 `null` 以在启用后关闭。输入音频转写并非模型原生功能，因为模型直接消费音频。转写通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的指引，而非模型实际听到的精确内容。客户端可以可选地设置转写所用的语言和提示词，这些为转写服务提供了额外的指引。 - `turn_detection: optional RealtimeTranscriptionSessionAudioInputTurnDetection or null` - 用于轮流检测的配置，可以是服务器端 VAD 或语义 VAD。可设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可选 Server VAD 或 Semantic VAD。可设置为 `null` 以关闭该功能，此时客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将基于音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型会基于音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更为高级，它使用话轮检测模型（结合 VAD）从语义上估计用户是否已经说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”逐渐减弱，模型会给出较低的话轮结束概率，并等待更长时间让用户继续说话。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更先进，它会结合 VAD 使用一个轮次判断模型来语义层面估计用户是否已说完，然后基于该概率动态设置一个超时时间。例如，如果用户的语音以“嗯……”之类的语气词收尾，模型会给出一个较低的轮次结束概率，并等待更长时间以便用户继续说话。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转写会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` transcription 会话中，turn detection 必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静音一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以开启简单的服务端 VAD。 + turn detection 类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，在模型已经正在响应时可能会无法创建响应。 - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选的超时时间，超过该时间后将自动触发模型响应。这 - 对于用户长时间停顿属于意外情况时很有用，例如电话 - 通话。模型将基于当前上下文有效地提示用户继续对话。 - 基于当前上下文。 + 可选超时时间，到达后将自动触发一次响应。 + 这在用户长时间停顿出乎意料的情况下很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话。 + 于当前上下文。 - 超时时间将在最后一个模型响应的音频播放完毕后开始计算， - 即它设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在最后一次模型响应的音频播放结束后应用， + 即它被设置为 `response.done` time plus audio playback duration. - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 达到超时时间时将发出与响应关联的事件）。 - 空闲超时目前仅支持 `server_vad` 模式。 + 一个 `input_audio_buffer.timeout_triggered` event (plus events + associated with the Response) will be emitted when the timeout is reached. + Idle timeout is currently only supported for `server_vad` mode. - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断（取消）任何正在进行的、具有输出到默认 - 对话（即。 `conversation` 的 `auto`）响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + Whether or not to automatically interrupt (cancel) any ongoing response with output to the default + conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete. - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音持续时间（以毫秒为单位）。默认为 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈值越高， - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义转折检测，使用模型来判断用户是否已说完话。 + 服务端语义轮次检测，通过模型判断用户何时已结束发言。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + turn detection 类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` @@ -996,7 +996,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户继续说的时间更长， `high` 则会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`、 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + Used only for `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续发言， `high` 会更快地作出响应。 `auto` 为默认值，相当于 `medium`. `low`, `medium`，以及 `high` 的最大超时分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -1008,26 +1008,26 @@ - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断任何正在进行的响应并输出到默认的 - 对话（即。 `conversation` 的 `auto`）。 + 当存在输出到默认 + conversation (i.e. `conversation` of `auto`) 时，是否自动中断任何正在进行的响应。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` -### 返回 +### Returns - `expires_at: number` - 客户端密钥的过期时间戳，单位为自纪元起的秒数。 + 客户端密钥的过期时间戳，以自纪元起的秒数表示。 - `session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse` - 会话配置，用于实时或转录会话。 + 实时会话或转录会话的会话配置。 - `RealtimeSessionCreateResponse object { id, object, type, 13 more }` @@ -1035,7 +1035,7 @@ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: "realtime.session"` @@ -1045,7 +1045,7 @@ - `type: "realtime"` - 要创建的会话类型。对于实时API始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -1097,13 +1097,13 @@ - `noise_reduction: optional object { type }` - 输入音频噪声抑制的配置。可设置为 `null` 以关闭。 - 噪声抑制会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提高模型性能。 + 输入音频降噪配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行处理。 + 对音频进行过滤可以通过改善对输入音频的感知，从而提高 VAD 和打断检测的准确率（减少误报），并提升模型表现。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `"near_field"` @@ -1111,7 +1111,7 @@ - `transcription: optional object { language, languages, model, prompt }` - 输入音频转录的配置，默认关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应视为输入音频内容的指导，而非模型所听到内容的精确反映。客户端可以选择设置转录的语言和提示，这些为转录服务提供额外指导。 + 输入音频转写配置，默认为关闭状态，可设置为 `null` 以在启用后关闭。输入音频转写并非模型原生功能，因为模型直接消费音频。转写通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的指引，而非模型实际听到的精确内容。客户端可以可选地设置转写所用的语言和提示词，这些为转写服务提供了额外的指引。 - `language: optional string` @@ -1119,17 +1119,17 @@ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -1153,76 +1153,76 @@ - `turn_detection: optional object { type, create_response, idle_timeout_ms, 4 more } or object { type, create_response, eagerness, interrupt_response } or null` - 用于轮流检测的配置，可以是服务器端 VAD 或语义 VAD。可设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可选 Server VAD 或 Semantic VAD。可设置为 `null` 以关闭该功能，此时客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将基于音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型会基于音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更为高级，它使用话轮检测模型（结合 VAD）从语义上估计用户是否已经说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”逐渐减弱，模型会给出较低的话轮结束概率，并等待更长时间让用户继续说话。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更先进，它会结合 VAD 使用一个轮次判断模型来语义层面估计用户是否已说完，然后基于该概率动态设置一个超时时间。例如，如果用户的语音以“嗯……”之类的语气词收尾，模型会给出一个较低的轮次结束概率，并等待更长时间以便用户继续说话。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转写会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` transcription 会话中，turn detection 必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静音一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以开启简单的服务端 VAD。 + turn detection 类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，在模型已经正在响应时可能会无法创建响应。 - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选的超时时间，超过该时间后将自动触发模型响应。这 - 对于用户长时间停顿属于意外情况时很有用，例如电话 - 通话。模型将基于当前上下文有效地提示用户继续对话。 - 基于当前上下文。 + 可选超时时间，到达后将自动触发一次响应。 + 这在用户长时间停顿出乎意料的情况下很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话。 + 于当前上下文。 - 超时时间将在最后一个模型响应的音频播放完毕后开始计算， - 即它设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在最后一次模型响应的音频播放结束后应用， + 即它被设置为 `response.done` time plus audio playback duration. - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 达到超时时间时将发出与响应关联的事件）。 - 空闲超时目前仅支持 `server_vad` 模式。 + 一个 `input_audio_buffer.timeout_triggered` event (plus events + associated with the Response) will be emitted when the timeout is reached. + Idle timeout is currently only supported for `server_vad` mode. - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断（取消）任何正在进行的、具有输出到默认 - 对话（即。 `conversation` 的 `auto`）响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + Whether or not to automatically interrupt (cancel) any ongoing response with output to the default + conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete. - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音持续时间（以毫秒为单位）。默认为 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈值越高， - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义转折检测，使用模型来判断用户是否已说完话。 + 服务端语义轮次检测，通过模型判断用户何时已结束发言。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + turn detection 类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` @@ -1232,7 +1232,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户继续说的时间更长， `high` 则会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`、 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + Used only for `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续发言， `high` 会更快地作出响应。 `auto` 为默认值，相当于 `medium`. `low`, `medium`，以及 `high` 的最大超时分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -1244,8 +1244,8 @@ - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断任何正在进行的响应并输出到默认的 - 对话（即。 `conversation` 的 `auto`）。 + 当存在输出到默认 + conversation (i.e. `conversation` of `auto`) 时，是否自动中断任何正在进行的响应。 - `output: optional object { format, speed, voice }` @@ -1255,28 +1255,28 @@ - `speed: optional number` - 模型语音响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口语化响应的速度，相对于原始速度的倍数。 + 1.0 为默认速度。0.25 为最低速度。1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中修改。 - 此参数是对生成的音频进行后处理调整， - 也可以提示模型说得更快或更慢。 + 此参数是对生成后音频的后处理调整，也 + 可以通过提示让模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `string` - `"alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `"alloy"` @@ -1301,28 +1301,28 @@ - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 预置到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型产生所需响应。可以指导模型响应的内容和格式（例如“极其简洁”、“表现友好”、“以下是良好响应的示例”）以及音频行为（例如“语速快”、“语气注入情感”、“频繁大笑”）。模型不保证遵循这些指令，但指令为模型提供了所需行为的指导。 + 预先添加到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型给出期望的响应。可以指示模型关于响应内容和格式（例如"极其简洁"、"表现得友好"、"以下是良好响应的示例"），以及关于音频行为（例如"快速讲话"、"在声音中注入情感"、"经常笑"）。指令不保证被模型遵循，但它们为模型提供了关于期望行为的指导。 - 请注意，服务器会设置默认指令，如果未设置此字段，将使用这些指令，并且它们会显示在 `session.created` 会话开始处的事件中。 + 请注意，服务端会设置默认指令，如果未设置此字段将使用默认指令，并且这些指令在 `session.created` 事件中于会话开始时可见。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供一个介于 1 到 4096 之间的整数，以 - 限制输出 token，或 `inf` 获取给定模型的最大可用 token 数。默认值为 - 给定模型。默认值为 `inf`. + 单个助手响应的最大输出令牌数， + 包括工具调用。提供介于 1 和 4096 之间的整数以 + 限制输出令牌，或 `inf` 以获取给定模型的可用 + 最大令牌数。默认为 `inf`. - `number` @@ -1332,13 +1332,13 @@ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -1380,9 +1380,9 @@ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将响应音频加上转录文本。 `["text"]` 可用于使 - 模型仅以文本形式响应，无法同时请求两者 `text` 和 `audio` 。 + 模型可以响应的模态集合。默认为 `["audio"]`,表示 + 模型将响应音频加文字转录。 `["text"]` 可用于使 + the model respond with text only. It is not possible to request both `text` 和 `audio` at the same time. - `"text"` @@ -1390,52 +1390,52 @@ - `prompt: optional ResponsePrompt or null` - 对提示模板及其变量的引用。 - [了解更多](/docs/guides/text?api-mode=responses#reusable-prompts). + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - 要使用的提示模板的唯一标识符。 + The unique identifier of the prompt template to use. - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选映射，用于替换你 - 提示中的变量。替换值可以是字符串，也可以是其他 - 响应输入类型，如图像或文件。 + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + A text input to the model. - `text: string` - 对模型的文本输入。 + The text input to the model. - `type: "input_text"` - 输入项的类型。始终为 `input_text`. + The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: ImageDetail` - 要发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`, 或 `original`。默认为 `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`。默认为 `auto`. - `"low"` @@ -1447,41 +1447,41 @@ - `type: "input_image"` - 输入项的类型。始终为 `input_image`. + The type of the input item. Always `input_image`. - `"input_image"` - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，或 data URL 中的 base64 编码图片。 + 发送给模型的图片 URL。可以是完整的 URL，也可以是 base64 编码的图片数据 URL。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的输入文件。 - `type: "input_file"` - 输入项的类型。始终为 `input_file`. + The type of the input item. Always `input_file`. - `"input_file"` - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 发送给模型的文件细节级别。使用 `auto` 可让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 使用量。使用 `low` 可使用较低成本的渲染，或使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -1491,41 +1491,41 @@ - `file_data: optional string` - 要发送给模型的文件内容。 + 发送给模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `version: optional string or null` - 提示模板的可选版本。 + 可选的提示模板版本。 - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 面向支持推理的 Realtime 模型（例如）的配置 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 对支持推理的 Realtime 模型（例如 + 限制支持推理的 Realtime 模型（例如）的推理力度 `gpt-realtime-2`. - `"minimal"` @@ -1540,16 +1540,16 @@ - `tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp` - 模型如何选择工具。提供一种字符串模式，或强制指定某个 - 函数/MCP 工具。 + 模型如何选择工具。提供一个字符串模式，或强制使用特定的 + function/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型是否调用工具以及调用哪个（如果有）工具。 + 控制模型调用哪个工具（如果有的话）。 - `none` 表示模型不会调用任何工具，而是生成一条消息。 + `none` 表示模型将不调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个 + `auto` 表示模型可以在生成消息或调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -1562,7 +1562,7 @@ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可强制模型调用指定的函数。 - `name: string` @@ -1576,7 +1576,7 @@ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -1600,9 +1600,9 @@ - `description: optional string` - 函数的描述，包括调用时机和方式 - 的指导，以及调用时应告知用户什么内容 - （如果有）。 + 函数的说明，包括何时以及如何调用的指导， + 以及调用时向用户说明哪些内容的指导 + （如有）。 - `name: optional string` @@ -1610,7 +1610,7 @@ - `parameters: optional unknown` - JSON Schema 格式的函数参数。 + 函数的参数，采用 JSON Schema 格式。 - `type: optional "function"` @@ -1620,16 +1620,16 @@ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供更多工具。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). + 通过远程模型上下文协议 (MCP) 服务器让模型访问额外的工具。 + （了解有关 MCP 的更多信息。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). - `server_label: string` - 该 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中标识它。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -1643,48 +1643,48 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或筛选器对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许使用的工具名称字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，既可以 - 用于自定义 MCP 服务器 URL，也可以用于服务连接器。你的应用 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可与远程 MCP 服务器配合使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`, 或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。必须提供其中 + `server_url`, `connector_id`, or `tunnel_id` 之一。详细了解 + 服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持的 `connector_id` 值为： + 目前支持 `connector_id` 的值为： - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -1704,56 +1704,56 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载的工具，并通过工具搜索发现。 - `headers: optional map[string] or null` 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具 - 关联的筛选器对象。 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`,或与工具关联的筛选器对象 + 这些工具需要审批。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当设置为 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -1765,60 +1765,60 @@ - `server_url: optional string` - MCP 服务器的 URL。以下任一项 `server_url`, `connector_id`, 或 - `tunnel_id` 必须提供。 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`, or + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而不是直接服务器 URL。以下任一项 - `server_url`, `connector_id`, 或 `tunnel_id` 必须提供。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 + `server_url`, `connector_id`, or `tunnel_id` 。 - `tracing: optional "auto" or object { group_id, metadata, workflow_name } or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入 [追踪仪表板](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦为会话启用了 追踪，便无法再修改该配置。 + 追踪。 - `auto` 将为会话创建一条 追踪，并使用默认值设置 - 工作流 名称、组 ID 和元数据。 + `auto` 将使用默认值创建一个会话 追踪，包括 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪，并为 追踪 配置选项设置默认值。始终 `auto`. + 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 针对 追踪 的细粒度配置。 + 对 追踪 的细粒度配置。 - `group_id: optional string` - 要附加到此 追踪 的组 ID，用于启用过滤和 - 在追踪仪表盘中进行分组。 + 附加到此 追踪 的 group id，用于在追踪仪表板中进行筛选和 + 分组。 - `metadata: optional unknown` - 要附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的过滤。 + 附加到此 追踪 的任意元数据，用于在追踪仪表板中进行 + 筛选。 - `workflow_name: optional string` - 要附加到此 工作流 的名称。这用于 - 在追踪仪表盘中命名该 追踪。 + 附加到此 追踪 的 工作流 名称。它用于在追踪仪表板中 + 为该 追踪 命名。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数超过模型的输入令牌限制时，对话将被截断，这意味着（从最早的开始）消息将不会包含在模型的上下文中。一个 32k 上下文模型，最大输出令牌数为 4,096，在发生截断前只能包含 28,224 个令牌在上下文中。 + 当对话中的 token 数量超过模型的输入 token 上限时，对话将被截断，这意味着部分消息（从最早的消息开始）将不会包含在模型的上下文中。拥有 32k 上下文、最大输出 token 为 4,096 的模型，在发生截断之前，其上下文中最多只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用量和成本的有效方法。 + 客户端可以配置截断行为，使用更低的最大 token 限制进行截断，这是一种有效控制 token 使用量和成本的方式。 - 截断会减少下一轮中的缓存令牌数（破坏缓存），因为消息会从上下文开头被丢弃。但是，客户端也可以配置截断以保留最多达到最大上下文大小一定比例的消息，这将减少未来截断的需求，从而提高缓存命中率。 + 截断会减少下一轮中缓存的 token 数量（破坏缓存），因为消息会从上下文的开头被丢弃。不过，客户端也可以将截断配置为保留最多占最大上下文大小一定比例的消息，从而减少后续截断的需要，进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会进行截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会进行截断，但如果对话超出模型的输入 token 上限，将改为返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话所使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超出输入 token 上限时报错。 - `"auto"` @@ -1826,11 +1826,11 @@ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多次轮次中分摊截断，有助于改善缓存令牌的使用。 + 在对话超出输入 token 上限后，保留其中一部分会话 token。这可以让你将截断分摊到多轮对话中，有助于改善缓存 token 的使用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，保留指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的 80%。这有助于减少截断频率并提高缓存率。 + 在对话超出输入 token 上限时，要保留的指令后会话 token 比例（`0.0` - `1.0`）。当对话超出输入 token 上限时，将该值设置为 `0.8` 意味着会丢弃消息，直到使用到最大允许 token 的 80%。这有助于降低截断发生频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -1840,11 +1840,11 @@ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，将使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后对话中允许的最大令牌数（包括工具定义）。例如，将其设置为 5,000 意味着当对话在指令后超过 5,000 个令牌时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令之后（其中包括工具定义）会话所允许的最大 token 数。例如，将其设置为 5,000 意味着当指令之后的会话超过 5,000 token 时就会发生截断。该值不能高于模型的上下文窗口大小减去最大输出 token 数。 - `RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }` @@ -1852,7 +1852,7 @@ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: string` @@ -1860,7 +1860,7 @@ - `type: "transcription"` - 会话类型。始终为 `transcription` 用于转录会话的。 + 会话类型。始终为 `transcription` 用于转录会话。 - `"transcription"` @@ -1876,11 +1876,11 @@ - `noise_reduction: optional object { type }` - 用于输入音频降噪的配置。 + 输入音频降噪的配置。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `transcription: optional object { language, languages, model, prompt }` @@ -1892,17 +1892,17 @@ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -1926,40 +1926,40 @@ - `turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null` - 用于开启检测的配置。可设置为 `null` 以关闭。服务端 - VAD 表示模型将根据 - 音频音量检测语音的开始和结束，并在用户语音结束时做出响应。对于 `gpt-realtime-whisper`，这必须 `null`；不支持 VAD。 + 轮次检测的配置。可设置为 `null` 以关闭。服务端 + VAD 意味着模型将根据 + 音频音量检测语音的开始和结束，并在用户语音结束时作出响应。对于 `gpt-realtime-whisper`,这必须是 `null`；不支持 VAD。 - `prefix_padding_ms: optional number` - VAD 检测到语音之前要包含的音频量（毫秒 - 毫秒为单位）。默认为 300 毫秒。 + VAD 检测到语音之前要包含的音频量（以 + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 检测语音停止所需的静音时长（毫秒）。默认 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + 用于检测语音停止的静默时长（以毫秒为单位）。默认为 + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - VAD 的激活阈值（0.0 到 1.0），默认为 0.5。一 - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + VAD 的激活阈值（0.0 到 1.0），默认为 0.5。较高的 + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `type: optional string` - 开启检测的类型，仅 `server_vad` 。 + 轮次检测类型，仅 `server_vad` 。 - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + - `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` @@ -2130,15 +2130,15 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `ClientSecretCreateResponse object { expires_at, session, value }` - 创建会话并为 Realtime API 生成客户端密钥后的响应。 + 为 Realtime API 创建会话和客户端密钥的响应。 - `expires_at: number` - 客户端密钥的过期时间戳，单位为自纪元起的秒数。 + 客户端密钥的过期时间戳，以自纪元起的秒数表示。 - `session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse` - 会话配置，用于实时或转录会话。 + 实时会话或转录会话的会话配置。 - `RealtimeSessionCreateResponse object { id, object, type, 13 more }` @@ -2146,7 +2146,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: "realtime.session"` @@ -2156,7 +2156,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "realtime"` - 要创建的会话类型。对于实时API始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -2208,13 +2208,13 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `noise_reduction: optional object { type }` - 输入音频噪声抑制的配置。可设置为 `null` 以关闭。 - 噪声抑制会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提高模型性能。 + 输入音频降噪配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行处理。 + 对音频进行过滤可以通过改善对输入音频的感知，从而提高 VAD 和打断检测的准确率（减少误报），并提升模型表现。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `"near_field"` @@ -2222,7 +2222,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `transcription: optional object { language, languages, model, prompt }` - 输入音频转录的配置，默认关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应视为输入音频内容的指导，而非模型所听到内容的精确反映。客户端可以选择设置转录的语言和提示，这些为转录服务提供额外指导。 + 输入音频转写配置，默认为关闭状态，可设置为 `null` 以在启用后关闭。输入音频转写并非模型原生功能，因为模型直接消费音频。转写通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的指引，而非模型实际听到的精确内容。客户端可以可选地设置转写所用的语言和提示词，这些为转写服务提供了额外的指引。 - `language: optional string` @@ -2230,17 +2230,17 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -2264,76 +2264,76 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `turn_detection: optional object { type, create_response, idle_timeout_ms, 4 more } or object { type, create_response, eagerness, interrupt_response } or null` - 用于轮流检测的配置，可以是服务器端 VAD 或语义 VAD。可设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可选 Server VAD 或 Semantic VAD。可设置为 `null` 以关闭该功能，此时客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将基于音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型会基于音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更为高级，它使用话轮检测模型（结合 VAD）从语义上估计用户是否已经说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”逐渐减弱，模型会给出较低的话轮结束概率，并等待更长时间让用户继续说话。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更先进，它会结合 VAD 使用一个轮次判断模型来语义层面估计用户是否已说完，然后基于该概率动态设置一个超时时间。例如，如果用户的语音以“嗯……”之类的语气词收尾，模型会给出一个较低的轮次结束概率，并等待更长时间以便用户继续说话。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转写会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` transcription 会话中，turn detection 必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静音一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以开启简单的服务端 VAD。 + turn detection 类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，在模型已经正在响应时可能会无法创建响应。 - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选的超时时间，超过该时间后将自动触发模型响应。这 - 对于用户长时间停顿属于意外情况时很有用，例如电话 - 通话。模型将基于当前上下文有效地提示用户继续对话。 - 基于当前上下文。 + 可选超时时间，到达后将自动触发一次响应。 + 这在用户长时间停顿出乎意料的情况下很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话。 + 于当前上下文。 - 超时时间将在最后一个模型响应的音频播放完毕后开始计算， - 即它设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在最后一次模型响应的音频播放结束后应用， + 即它被设置为 `response.done` time plus audio playback duration. - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 达到超时时间时将发出与响应关联的事件）。 - 空闲超时目前仅支持 `server_vad` 模式。 + 一个 `input_audio_buffer.timeout_triggered` event (plus events + associated with the Response) will be emitted when the timeout is reached. + Idle timeout is currently only supported for `server_vad` mode. - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断（取消）任何正在进行的、具有输出到默认 - 对话（即。 `conversation` 的 `auto`）响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + Whether or not to automatically interrupt (cancel) any ongoing response with output to the default + conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete. - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音持续时间（以毫秒为单位）。默认为 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈值越高， - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义转折检测，使用模型来判断用户是否已说完话。 + 服务端语义轮次检测，通过模型判断用户何时已结束发言。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + turn detection 类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` @@ -2343,7 +2343,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户继续说的时间更长， `high` 则会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`、 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + Used only for `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续发言， `high` 会更快地作出响应。 `auto` 为默认值，相当于 `medium`. `low`, `medium`，以及 `high` 的最大超时分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -2355,8 +2355,8 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断任何正在进行的响应并输出到默认的 - 对话（即。 `conversation` 的 `auto`）。 + 当存在输出到默认 + conversation (i.e. `conversation` of `auto`) 时，是否自动中断任何正在进行的响应。 - `output: optional object { format, speed, voice }` @@ -2366,28 +2366,28 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `speed: optional number` - 模型语音响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口语化响应的速度，相对于原始速度的倍数。 + 1.0 为默认速度。0.25 为最低速度。1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中修改。 - 此参数是对生成的音频进行后处理调整， - 也可以提示模型说得更快或更慢。 + 此参数是对生成后音频的后处理调整，也 + 可以通过提示让模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `string` - `"alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `"alloy"` @@ -2412,28 +2412,28 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 预置到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型产生所需响应。可以指导模型响应的内容和格式（例如“极其简洁”、“表现友好”、“以下是良好响应的示例”）以及音频行为（例如“语速快”、“语气注入情感”、“频繁大笑”）。模型不保证遵循这些指令，但指令为模型提供了所需行为的指导。 + 预先添加到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型给出期望的响应。可以指示模型关于响应内容和格式（例如"极其简洁"、"表现得友好"、"以下是良好响应的示例"），以及关于音频行为（例如"快速讲话"、"在声音中注入情感"、"经常笑"）。指令不保证被模型遵循，但它们为模型提供了关于期望行为的指导。 - 请注意，服务器会设置默认指令，如果未设置此字段，将使用这些指令，并且它们会显示在 `session.created` 会话开始处的事件中。 + 请注意，服务端会设置默认指令，如果未设置此字段将使用默认指令，并且这些指令在 `session.created` 事件中于会话开始时可见。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供一个介于 1 到 4096 之间的整数，以 - 限制输出 token，或 `inf` 获取给定模型的最大可用 token 数。默认值为 - 给定模型。默认值为 `inf`. + 单个助手响应的最大输出令牌数， + 包括工具调用。提供介于 1 和 4096 之间的整数以 + 限制输出令牌，或 `inf` 以获取给定模型的可用 + 最大令牌数。默认为 `inf`. - `number` @@ -2443,13 +2443,13 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -2491,9 +2491,9 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将响应音频加上转录文本。 `["text"]` 可用于使 - 模型仅以文本形式响应，无法同时请求两者 `text` 和 `audio` 。 + 模型可以响应的模态集合。默认为 `["audio"]`,表示 + 模型将响应音频加文字转录。 `["text"]` 可用于使 + the model respond with text only. It is not possible to request both `text` 和 `audio` at the same time. - `"text"` @@ -2501,52 +2501,52 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `prompt: optional ResponsePrompt or null` - 对提示模板及其变量的引用。 - [了解更多](/docs/guides/text?api-mode=responses#reusable-prompts). + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - 要使用的提示模板的唯一标识符。 + The unique identifier of the prompt template to use. - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选映射，用于替换你 - 提示中的变量。替换值可以是字符串，也可以是其他 - 响应输入类型，如图像或文件。 + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + A text input to the model. - `text: string` - 对模型的文本输入。 + The text input to the model. - `type: "input_text"` - 输入项的类型。始终为 `input_text`. + The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: ImageDetail` - 要发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`, 或 `original`。默认为 `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`。默认为 `auto`. - `"low"` @@ -2558,41 +2558,41 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "input_image"` - 输入项的类型。始终为 `input_image`. + The type of the input item. Always `input_image`. - `"input_image"` - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，或 data URL 中的 base64 编码图片。 + 发送给模型的图片 URL。可以是完整的 URL，也可以是 base64 编码的图片数据 URL。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的输入文件。 - `type: "input_file"` - 输入项的类型。始终为 `input_file`. + The type of the input item. Always `input_file`. - `"input_file"` - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 发送给模型的文件细节级别。使用 `auto` 可让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 使用量。使用 `low` 可使用较低成本的渲染，或使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -2602,41 +2602,41 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `file_data: optional string` - 要发送给模型的文件内容。 + 发送给模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `version: optional string or null` - 提示模板的可选版本。 + 可选的提示模板版本。 - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 面向支持推理的 Realtime 模型（例如）的配置 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 对支持推理的 Realtime 模型（例如 + 限制支持推理的 Realtime 模型（例如）的推理力度 `gpt-realtime-2`. - `"minimal"` @@ -2651,16 +2651,16 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp` - 模型如何选择工具。提供一种字符串模式，或强制指定某个 - 函数/MCP 工具。 + 模型如何选择工具。提供一个字符串模式，或强制使用特定的 + function/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型是否调用工具以及调用哪个（如果有）工具。 + 控制模型调用哪个工具（如果有的话）。 - `none` 表示模型不会调用任何工具，而是生成一条消息。 + `none` 表示模型将不调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个 + `auto` 表示模型可以在生成消息或调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -2673,7 +2673,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可强制模型调用指定的函数。 - `name: string` @@ -2687,7 +2687,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -2711,9 +2711,9 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `description: optional string` - 函数的描述，包括调用时机和方式 - 的指导，以及调用时应告知用户什么内容 - （如果有）。 + 函数的说明，包括何时以及如何调用的指导， + 以及调用时向用户说明哪些内容的指导 + （如有）。 - `name: optional string` @@ -2721,7 +2721,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `parameters: optional unknown` - JSON Schema 格式的函数参数。 + 函数的参数，采用 JSON Schema 格式。 - `type: optional "function"` @@ -2731,16 +2731,16 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供更多工具。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). + 通过远程模型上下文协议 (MCP) 服务器让模型访问额外的工具。 + （了解有关 MCP 的更多信息。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). - `server_label: string` - 该 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中标识它。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -2754,48 +2754,48 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或筛选器对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许使用的工具名称字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，既可以 - 用于自定义 MCP 服务器 URL，也可以用于服务连接器。你的应用 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可与远程 MCP 服务器配合使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`, 或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。必须提供其中 + `server_url`, `connector_id`, or `tunnel_id` 之一。详细了解 + 服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持的 `connector_id` 值为： + 目前支持 `connector_id` 的值为： - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -2815,56 +2815,56 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载的工具，并通过工具搜索发现。 - `headers: optional map[string] or null` 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具 - 关联的筛选器对象。 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`,或与工具关联的筛选器对象 + 这些工具需要审批。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当设置为 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -2876,60 +2876,60 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `server_url: optional string` - MCP 服务器的 URL。以下任一项 `server_url`, `connector_id`, 或 - `tunnel_id` 必须提供。 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`, or + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而不是直接服务器 URL。以下任一项 - `server_url`, `connector_id`, 或 `tunnel_id` 必须提供。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 + `server_url`, `connector_id`, or `tunnel_id` 。 - `tracing: optional "auto" or object { group_id, metadata, workflow_name } or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入 [追踪仪表板](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦为会话启用了 追踪，便无法再修改该配置。 + 追踪。 - `auto` 将为会话创建一条 追踪，并使用默认值设置 - 工作流 名称、组 ID 和元数据。 + `auto` 将使用默认值创建一个会话 追踪，包括 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪，并为 追踪 配置选项设置默认值。始终 `auto`. + 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 针对 追踪 的细粒度配置。 + 对 追踪 的细粒度配置。 - `group_id: optional string` - 要附加到此 追踪 的组 ID，用于启用过滤和 - 在追踪仪表盘中进行分组。 + 附加到此 追踪 的 group id，用于在追踪仪表板中进行筛选和 + 分组。 - `metadata: optional unknown` - 要附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的过滤。 + 附加到此 追踪 的任意元数据，用于在追踪仪表板中进行 + 筛选。 - `workflow_name: optional string` - 要附加到此 工作流 的名称。这用于 - 在追踪仪表盘中命名该 追踪。 + 附加到此 追踪 的 工作流 名称。它用于在追踪仪表板中 + 为该 追踪 命名。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数超过模型的输入令牌限制时，对话将被截断，这意味着（从最早的开始）消息将不会包含在模型的上下文中。一个 32k 上下文模型，最大输出令牌数为 4,096，在发生截断前只能包含 28,224 个令牌在上下文中。 + 当对话中的 token 数量超过模型的输入 token 上限时，对话将被截断，这意味着部分消息（从最早的消息开始）将不会包含在模型的上下文中。拥有 32k 上下文、最大输出 token 为 4,096 的模型，在发生截断之前，其上下文中最多只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用量和成本的有效方法。 + 客户端可以配置截断行为，使用更低的最大 token 限制进行截断，这是一种有效控制 token 使用量和成本的方式。 - 截断会减少下一轮中的缓存令牌数（破坏缓存），因为消息会从上下文开头被丢弃。但是，客户端也可以配置截断以保留最多达到最大上下文大小一定比例的消息，这将减少未来截断的需求，从而提高缓存命中率。 + 截断会减少下一轮中缓存的 token 数量（破坏缓存），因为消息会从上下文的开头被丢弃。不过，客户端也可以将截断配置为保留最多占最大上下文大小一定比例的消息，从而减少后续截断的需要，进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会进行截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会进行截断，但如果对话超出模型的输入 token 上限，将改为返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话所使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超出输入 token 上限时报错。 - `"auto"` @@ -2937,11 +2937,11 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多次轮次中分摊截断，有助于改善缓存令牌的使用。 + 在对话超出输入 token 上限后，保留其中一部分会话 token。这可以让你将截断分摊到多轮对话中，有助于改善缓存 token 的使用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，保留指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的 80%。这有助于减少截断频率并提高缓存率。 + 在对话超出输入 token 上限时，要保留的指令后会话 token 比例（`0.0` - `1.0`）。当对话超出输入 token 上限时，将该值设置为 `0.8` 意味着会丢弃消息，直到使用到最大允许 token 的 80%。这有助于降低截断发生频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -2951,11 +2951,11 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，将使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后对话中允许的最大令牌数（包括工具定义）。例如，将其设置为 5,000 意味着当对话在指令后超过 5,000 个令牌时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令之后（其中包括工具定义）会话所允许的最大 token 数。例如，将其设置为 5,000 意味着当指令之后的会话超过 5,000 token 时就会发生截断。该值不能高于模型的上下文窗口大小减去最大输出 token 数。 - `RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }` @@ -2963,7 +2963,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: string` @@ -2971,7 +2971,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "transcription"` - 会话类型。始终为 `transcription` 用于转录会话的。 + 会话类型。始终为 `transcription` 用于转录会话。 - `"transcription"` @@ -2987,11 +2987,11 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `noise_reduction: optional object { type }` - 用于输入音频降噪的配置。 + 输入音频降噪的配置。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `transcription: optional object { language, languages, model, prompt }` @@ -3003,17 +3003,17 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -3037,40 +3037,40 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null` - 用于开启检测的配置。可设置为 `null` 以关闭。服务端 - VAD 表示模型将根据 - 音频音量检测语音的开始和结束，并在用户语音结束时做出响应。对于 `gpt-realtime-whisper`，这必须 `null`；不支持 VAD。 + 轮次检测的配置。可设置为 `null` 以关闭。服务端 + VAD 意味着模型将根据 + 音频音量检测语音的开始和结束，并在用户语音结束时作出响应。对于 `gpt-realtime-whisper`,这必须是 `null`；不支持 VAD。 - `prefix_padding_ms: optional number` - VAD 检测到语音之前要包含的音频量（毫秒 - 毫秒为单位）。默认为 300 毫秒。 + VAD 检测到语音之前要包含的音频量（以 + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 检测语音停止所需的静音时长（毫秒）。默认 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + 用于检测语音停止的静默时长（以毫秒为单位）。默认为 + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - VAD 的激活阈值（0.0 到 1.0），默认为 0.5。一 - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + VAD 的激活阈值（0.0 到 1.0），默认为 0.5。较高的 + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `type: optional string` - 开启检测的类型，仅 `server_vad` 。 + 轮次检测类型，仅 `server_vad` 。 - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + - `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` @@ -3078,7 +3078,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ 生成的客户端密钥值。 -### 实时会话创建响应 +### Realtime Session Create Response - `RealtimeSessionCreateResponse object { id, object, type, 13 more }` @@ -3086,7 +3086,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: "realtime.session"` @@ -3096,7 +3096,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "realtime"` - 要创建的会话类型。对于实时API始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -3148,13 +3148,13 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `noise_reduction: optional object { type }` - 输入音频噪声抑制的配置。可设置为 `null` 以关闭。 - 噪声抑制会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提高模型性能。 + 输入音频降噪配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行处理。 + 对音频进行过滤可以通过改善对输入音频的感知，从而提高 VAD 和打断检测的准确率（减少误报），并提升模型表现。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `"near_field"` @@ -3162,7 +3162,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `transcription: optional object { language, languages, model, prompt }` - 输入音频转录的配置，默认关闭，可设置为 `null` 以在开启后关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应视为输入音频内容的指导，而非模型所听到内容的精确反映。客户端可以选择设置转录的语言和提示，这些为转录服务提供额外指导。 + 输入音频转写配置，默认为关闭状态，可设置为 `null` 以在启用后关闭。输入音频转写并非模型原生功能，因为模型直接消费音频。转写通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的指引，而非模型实际听到的精确内容。客户端可以可选地设置转写所用的语言和提示词，这些为转写服务提供了额外的指引。 - `language: optional string` @@ -3170,17 +3170,17 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -3204,76 +3204,76 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `turn_detection: optional object { type, create_response, idle_timeout_ms, 4 more } or object { type, create_response, eagerness, interrupt_response } or null` - 用于轮流检测的配置，可以是服务器端 VAD 或语义 VAD。可设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可选 Server VAD 或 Semantic VAD。可设置为 `null` 以关闭该功能，此时客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将基于音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型会基于音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更为高级，它使用话轮检测模型（结合 VAD）从语义上估计用户是否已经说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”逐渐减弱，模型会给出较低的话轮结束概率，并等待更长时间让用户继续说话。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更先进，它会结合 VAD 使用一个轮次判断模型来语义层面估计用户是否已说完，然后基于该概率动态设置一个超时时间。例如，如果用户的语音以“嗯……”之类的语气词收尾，模型会给出一个较低的轮次结束概率，并等待更长时间以便用户继续说话。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转写会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` transcription 会话中，turn detection 必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静音一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静默一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以开启简单的服务端 VAD。 + turn detection 类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，在模型已经正在响应时可能会无法创建响应。 - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `idle_timeout_ms: optional number or null` - 可选的超时时间，超过该时间后将自动触发模型响应。这 - 对于用户长时间停顿属于意外情况时很有用，例如电话 - 通话。模型将基于当前上下文有效地提示用户继续对话。 - 基于当前上下文。 + 可选超时时间，到达后将自动触发一次响应。 + 这在用户长时间停顿出乎意料的情况下很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话。 + 于当前上下文。 - 超时时间将在最后一个模型响应的音频播放完毕后开始计算， - 即它设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在最后一次模型响应的音频播放结束后应用， + 即它被设置为 `response.done` time plus audio playback duration. - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 达到超时时间时将发出与响应关联的事件）。 - 空闲超时目前仅支持 `server_vad` 模式。 + 一个 `input_audio_buffer.timeout_triggered` event (plus events + associated with the Response) will be emitted when the timeout is reached. + Idle timeout is currently only supported for `server_vad` mode. - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断（取消）任何正在进行的、具有输出到默认 - 对话（即。 `conversation` 的 `auto`）响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + Whether or not to automatically interrupt (cancel) any ongoing response with output to the default + conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete. - 如果两者都 `create_response` 和 `interrupt_response` 设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音持续时间（以毫秒为单位）。默认为 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈值越高， - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义转折检测，使用模型来判断用户是否已说完话。 + 服务端语义轮次检测，通过模型判断用户何时已结束发言。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + turn detection 类型， `semantic_vad` 以开启 Semantic VAD。 - `"semantic_vad"` @@ -3283,7 +3283,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 会等待用户继续说的时间更长， `high` 则会更快地响应。 `auto` 是默认值，等同于 `medium`. `low`, `medium`、 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + Used only for `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以便用户继续发言， `high` 会更快地作出响应。 `auto` 为默认值，相当于 `medium`. `low`, `medium`，以及 `high` 的最大超时分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -3295,8 +3295,8 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `interrupt_response: optional boolean` - 当 VAD 开始事件发生时，是否自动中断任何正在进行的响应并输出到默认的 - 对话（即。 `conversation` 的 `auto`）。 + 当存在输出到默认 + conversation (i.e. `conversation` of `auto`) 时，是否自动中断任何正在进行的响应。 - `output: optional object { format, speed, voice }` @@ -3306,28 +3306,28 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `speed: optional number` - 模型语音响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口语化响应的速度，相对于原始速度的倍数。 + 1.0 为默认速度。0.25 为最低速度。1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中修改。 - 此参数是对生成的音频进行后处理调整， - 也可以提示模型说得更快或更慢。 + 此参数是对生成后音频的后处理调整，也 + 可以通过提示让模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `string` - `"alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。一旦模型至少响应过一次音频，语音在 - 会话期间不能更改。当前 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, - `shimmer`, `verse`, `marin`、 `cedar`。我们建议使用 `marin` 和 `cedar` 以获得 + 模型用于回应的声音。一旦模型已经以音频回应过至少一次，会话期间就无法再更改声音。当前 + 会话中的声音选项包括 + 声音选项有 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 - `"alloy"` @@ -3352,28 +3352,28 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 预置到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型产生所需响应。可以指导模型响应的内容和格式（例如“极其简洁”、“表现友好”、“以下是良好响应的示例”）以及音频行为（例如“语速快”、“语气注入情感”、“频繁大笑”）。模型不保证遵循这些指令，但指令为模型提供了所需行为的指导。 + 预先添加到模型调用的默认系统指令（即系统消息）。此字段允许客户端引导模型给出期望的响应。可以指示模型关于响应内容和格式（例如"极其简洁"、"表现得友好"、"以下是良好响应的示例"），以及关于音频行为（例如"快速讲话"、"在声音中注入情感"、"经常笑"）。指令不保证被模型遵循，但它们为模型提供了关于期望行为的指导。 - 请注意，服务器会设置默认指令，如果未设置此字段，将使用这些指令，并且它们会显示在 `session.created` 会话开始处的事件中。 + 请注意，服务端会设置默认指令，如果未设置此字段将使用默认指令，并且这些指令在 `session.created` 事件中于会话开始时可见。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供一个介于 1 到 4096 之间的整数，以 - 限制输出 token，或 `inf` 获取给定模型的最大可用 token 数。默认值为 - 给定模型。默认值为 `inf`. + 单个助手响应的最大输出令牌数， + 包括工具调用。提供介于 1 和 4096 之间的整数以 + 限制输出令牌，或 `inf` 以获取给定模型的可用 + 最大令牌数。默认为 `inf`. - `number` @@ -3383,13 +3383,13 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -3431,9 +3431,9 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将响应音频加上转录文本。 `["text"]` 可用于使 - 模型仅以文本形式响应，无法同时请求两者 `text` 和 `audio` 。 + 模型可以响应的模态集合。默认为 `["audio"]`,表示 + 模型将响应音频加文字转录。 `["text"]` 可用于使 + the model respond with text only. It is not possible to request both `text` 和 `audio` at the same time. - `"text"` @@ -3441,52 +3441,52 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `prompt: optional ResponsePrompt or null` - 对提示模板及其变量的引用。 - [了解更多](/docs/guides/text?api-mode=responses#reusable-prompts). + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - 要使用的提示模板的唯一标识符。 + The unique identifier of the prompt template to use. - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选映射，用于替换你 - 提示中的变量。替换值可以是字符串，也可以是其他 - 响应输入类型，如图像或文件。 + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + A text input to the model. - `text: string` - 对模型的文本输入。 + The text input to the model. - `type: "input_text"` - 输入项的类型。始终为 `input_text`. + The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: ImageDetail` - 要发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`, 或 `original`。默认为 `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`。默认为 `auto`. - `"low"` @@ -3498,41 +3498,41 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "input_image"` - 输入项的类型。始终为 `input_image`. + The type of the input item. Always `input_image`. - `"input_image"` - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，或 data URL 中的 base64 编码图片。 + 发送给模型的图片 URL。可以是完整的 URL，也可以是 base64 编码的图片数据 URL。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的输入文件。 - `type: "input_file"` - 输入项的类型。始终为 `input_file`. + The type of the input item. Always `input_file`. - `"input_file"` - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 发送给模型的文件细节级别。使用 `auto` 可让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 使用量。使用 `low` 可使用较低成本的渲染，或使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -3542,41 +3542,41 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `file_data: optional string` - 要发送给模型的文件内容。 + 发送给模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 发送给模型的文件 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点从请求的 `prompt_cache_options.ttl`；继承其 TTL；边界不会四舍五入到令牌块。 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: "explicit"` - 断点模式。始终为 `explicit`. + The breakpoint mode. Always `explicit`. - `"explicit"` - `version: optional string or null` - 提示模板的可选版本。 + 可选的提示模板版本。 - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 面向支持推理的 Realtime 模型（例如）的配置 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 对支持推理的 Realtime 模型（例如 + 限制支持推理的 Realtime 模型（例如）的推理力度 `gpt-realtime-2`. - `"minimal"` @@ -3591,16 +3591,16 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp` - 模型如何选择工具。提供一种字符串模式，或强制指定某个 - 函数/MCP 工具。 + 模型如何选择工具。提供一个字符串模式，或强制使用特定的 + function/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型是否调用工具以及调用哪个（如果有）工具。 + 控制模型调用哪个工具（如果有的话）。 - `none` 表示模型不会调用任何工具，而是生成一条消息。 + `none` 表示模型将不调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个 + `auto` 表示模型可以在生成消息或调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -3613,7 +3613,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可强制模型调用指定的函数。 - `name: string` @@ -3627,7 +3627,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -3651,9 +3651,9 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `description: optional string` - 函数的描述，包括调用时机和方式 - 的指导，以及调用时应告知用户什么内容 - （如果有）。 + 函数的说明，包括何时以及如何调用的指导， + 以及调用时向用户说明哪些内容的指导 + （如有）。 - `name: optional string` @@ -3661,7 +3661,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `parameters: optional unknown` - JSON Schema 格式的函数参数。 + 函数的参数，采用 JSON Schema 格式。 - `type: optional "function"` @@ -3671,16 +3671,16 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供更多工具。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). + 通过远程模型上下文协议 (MCP) 服务器让模型访问额外的工具。 + （了解有关 MCP 的更多信息。 [了解有关 MCP 的更多信息](/docs/guides/tools-remote-mcp). - `server_label: string` - 该 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中标识它。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -3694,48 +3694,48 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或筛选器对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许使用的工具名称字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，既可以 - 用于自定义 MCP 服务器 URL，也可以用于服务连接器。你的应用 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可与远程 MCP 服务器配合使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`, 或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。必须提供其中 + `server_url`, `connector_id`, or `tunnel_id` 之一。详细了解 + 服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持的 `connector_id` 值为： + 目前支持 `connector_id` 的值为： - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -3755,56 +3755,56 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟加载的工具，并通过工具搜索发现。 - `headers: optional map[string] or null` 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具 - 关联的筛选器对象。 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`,或与工具关联的筛选器对象 + 这些工具需要审批。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的筛选器对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果某个 - MCP 服务器 [带有注释 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 它将匹配此过滤器。 + 指示工具是否修改数据或是否为只读。如果某个 + MCP 服务器已 [标注为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + ，它将与此筛选器匹配。 - `tool_names: optional array of string` - 允许的工具名称列表。 + 允许使用的工具名称列表。 - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 - `never`。当设置为 `always`，时，所有工具都需要审批。当设置为 - 设置为 `never`，时，所有工具都不需要审批。 + 为所有工具指定统一的审批策略。可选值为 `always` 或 + `never`。当设置为 `always`，时,所有工具都需要审批。当设置为 + 设置为 `never`，时,所有工具都不需要审批。 - `"always"` @@ -3816,60 +3816,60 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `server_url: optional string` - MCP 服务器的 URL。以下任一项 `server_url`, `connector_id`, 或 - `tunnel_id` 必须提供。 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`, or + `tunnel_id` 。 - `tunnel_id: optional string` - 要使用的 Secure MCP Tunnel ID，而不是直接服务器 URL。以下任一项 - `server_url`, `connector_id`, 或 `tunnel_id` 必须提供。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 + `server_url`, `connector_id`, or `tunnel_id` 。 - `tracing: optional "auto" or object { group_id, metadata, workflow_name } or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入 [追踪仪表板](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦为会话启用了 追踪，便无法再修改该配置。 + 追踪。 - `auto` 将为会话创建一条 追踪，并使用默认值设置 - 工作流 名称、组 ID 和元数据。 + `auto` 将使用默认值创建一个会话 追踪，包括 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪，并为 追踪 配置选项设置默认值。始终 `auto`. + 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 针对 追踪 的细粒度配置。 + 对 追踪 的细粒度配置。 - `group_id: optional string` - 要附加到此 追踪 的组 ID，用于启用过滤和 - 在追踪仪表盘中进行分组。 + 附加到此 追踪 的 group id，用于在追踪仪表板中进行筛选和 + 分组。 - `metadata: optional unknown` - 要附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的过滤。 + 附加到此 追踪 的任意元数据，用于在追踪仪表板中进行 + 筛选。 - `workflow_name: optional string` - 要附加到此 工作流 的名称。这用于 - 在追踪仪表盘中命名该 追踪。 + 附加到此 追踪 的 工作流 名称。它用于在追踪仪表板中 + 为该 追踪 命名。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数超过模型的输入令牌限制时，对话将被截断，这意味着（从最早的开始）消息将不会包含在模型的上下文中。一个 32k 上下文模型，最大输出令牌数为 4,096，在发生截断前只能包含 28,224 个令牌在上下文中。 + 当对话中的 token 数量超过模型的输入 token 上限时，对话将被截断，这意味着部分消息（从最早的消息开始）将不会包含在模型的上下文中。拥有 32k 上下文、最大输出 token 为 4,096 的模型，在发生截断之前，其上下文中最多只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用量和成本的有效方法。 + 客户端可以配置截断行为，使用更低的最大 token 限制进行截断，这是一种有效控制 token 使用量和成本的方式。 - 截断会减少下一轮中的缓存令牌数（破坏缓存），因为消息会从上下文开头被丢弃。但是，客户端也可以配置截断以保留最多达到最大上下文大小一定比例的消息，这将减少未来截断的需求，从而提高缓存命中率。 + 截断会减少下一轮中缓存的 token 数量（破坏缓存），因为消息会从上下文的开头被丢弃。不过，客户端也可以将截断配置为保留最多占最大上下文大小一定比例的消息，从而减少后续截断的需要，进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会进行截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会进行截断，但如果对话超出模型的输入 token 上限，将改为返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话所使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超出输入 token 上限时报错。 - `"auto"` @@ -3877,11 +3877,11 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多次轮次中分摊截断，有助于改善缓存令牌的使用。 + 在对话超出输入 token 上限后，保留其中一部分会话 token。这可以让你将截断分摊到多轮对话中，有助于改善缓存 token 的使用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，保留指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的 80%。这有助于减少截断频率并提高缓存率。 + 在对话超出输入 token 上限时，要保留的指令后会话 token 比例（`0.0` - `1.0`）。当对话超出输入 token 上限时，将该值设置为 `0.8` 意味着会丢弃消息，直到使用到最大允许 token 的 80%。这有助于降低截断发生频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -3891,13 +3891,13 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，将使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后对话中允许的最大令牌数（包括工具定义）。例如，将其设置为 5,000 意味着当对话在指令后超过 5,000 个令牌时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令之后（其中包括工具定义）会话所允许的最大 token 数。例如，将其设置为 5,000 意味着当指令之后的会话超过 5,000 token 时就会发生截断。该值不能高于模型的上下文窗口大小减去最大输出 token 数。 -### 实时转写会话创建响应 +### Realtime Transcription Session Create Response - `RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }` @@ -3905,7 +3905,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `id: string` - 会话的唯一标识符，格式为 `sess_1234567890abcdef`. + 会话的唯一标识符，类似于 `sess_1234567890abcdef`. - `object: string` @@ -3913,7 +3913,7 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `type: "transcription"` - 会话类型。始终为 `transcription` 用于转录会话的。 + 会话类型。始终为 `transcription` 用于转录会话。 - `"transcription"` @@ -3965,11 +3965,11 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `noise_reduction: optional object { type }` - 用于输入音频降噪的配置。 + 输入音频降噪的配置。 - `type: optional NoiseReductionType` - 噪声抑制的类型。 `near_field` 适用于近距离麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本电脑或会议室的麦克风。 + 降噪类型。 `near_field` 适用于耳机等近讲麦克风， `far_field` 适用于笔记本电脑或会议室麦克风等远场麦克风。 - `"near_field"` @@ -3985,17 +3985,17 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `languages: optional array of string` - 为转录配置的可能的输入音频语言，使用 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式。 + 为转录配置的可用输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`、 `gpt-realtime-whisper`. + 用于转录的模型。当前可选值为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`. - `"whisper-1"` @@ -4019,68 +4019,68 @@ curl -X POST https://api.openai.com/v1/realtime/client_secrets \ - `turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null` - 用于开启检测的配置。可设置为 `null` 以关闭。服务端 - VAD 表示模型将根据 - 音频音量检测语音的开始和结束，并在用户语音结束时做出响应。对于 `gpt-realtime-whisper`，这必须 `null`；不支持 VAD。 + 轮次检测的配置。可设置为 `null` 以关闭。服务端 + VAD 意味着模型将根据 + 音频音量检测语音的开始和结束，并在用户语音结束时作出响应。对于 `gpt-realtime-whisper`,这必须是 `null`；不支持 VAD。 - `prefix_padding_ms: optional number` - VAD 检测到语音之前要包含的音频量（毫秒 - 毫秒为单位）。默认为 300 毫秒。 + VAD 检测到语音之前要包含的音频量（以 + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 检测语音停止所需的静音时长（毫秒）。默认 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + 用于检测语音停止的静默时长（以毫秒为单位）。默认为 + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - VAD 的激活阈值（0.0 到 1.0），默认为 0.5。一 - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + VAD 的激活阈值（0.0 到 1.0），默认为 0.5。较高的 + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `type: optional string` - 开启检测的类型，仅 `server_vad` 。 + 轮次检测类型，仅 `server_vad` 。 - `expires_at: optional number` - 会话的过期时间戳，单位为自纪元起的秒数。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 在服务器输出中包含的其他字段。 + 要包含在服务端输出中的额外字段。 - - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + - `item.input_audio_transcription.logprobs`:为输入音频转录包含 logprobs。 - `"item.input_audio_transcription.logprobs"` -### 实时转写会话轮次检测 +### Realtime Transcription Session Turn Detection - `RealtimeTranscriptionSessionTurnDetection object { prefix_padding_ms, silence_duration_ms, threshold, type }` - 用于开启检测的配置。可设置为 `null` 以关闭。服务端 - VAD 表示模型将根据 - 音频音量检测语音的开始和结束，并在用户语音结束时做出响应。对于 `gpt-realtime-whisper`，这必须 `null`；不支持 VAD。 + 轮次检测的配置。可设置为 `null` 以关闭。服务端 + VAD 意味着模型将根据 + 音频音量检测语音的开始和结束，并在用户语音结束时作出响应。对于 `gpt-realtime-whisper`,这必须是 `null`；不支持 VAD。 - `prefix_padding_ms: optional number` - VAD 检测到语音之前要包含的音频量（毫秒 - 毫秒为单位）。默认为 300 毫秒。 + VAD 检测到语音之前要包含的音频量（以 + milliseconds). Defaults to 300ms. - `silence_duration_ms: optional number` - 检测语音停止所需的静音时长（毫秒）。默认 - 500 毫秒。值越短，模型响应越快， - 但可能会在用户的短暂停顿中插入回应。 + 用于检测语音停止的静默时长（以毫秒为单位）。默认为 + to 500ms. With shorter values the model will respond more quickly, + but may jump in on short pauses from the user. - `threshold: optional number` - VAD 的激活阈值（0.0 到 1.0），默认为 0.5。一 - 需要更大的音频才能激活模型，因此 - 在嘈杂环境中可能表现更好。 + VAD 的激活阈值（0.0 到 1.0），默认为 0.5。较高的 + higher threshold will require louder audio to activate the model, and + thus might perform better in noisy environments. - `type: optional string` - 开启检测的类型，仅 `server_vad` 。 + 轮次检测类型，仅 `server_vad` 。 diff --git a/docs/zh/api/reference/resources/realtime/subresources/client_secrets/methods/create.md b/docs/zh/api/reference/resources/realtime/subresources/client_secrets/methods/create.md index 12e4db9..f2e9bcc 100644 --- a/docs/zh/api/reference/resources/realtime/subresources/client_secrets/methods/create.md +++ b/docs/zh/api/reference/resources/realtime/subresources/client_secrets/methods/create.md @@ -1,45 +1,45 @@ -> 有关完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 末尾添加 `.md` 来获取文档页面的 Markdown 版本。 ## 创建客户端密钥 **post** `/realtime/client_secrets` -创建带有相关会话配置的 Realtime 客户端密钥。 +创建一个 Realtime 客户端密钥，并附带会话配置。 -客户端密钥是短时令牌，可传递给客户端应用， -如 Web 前端或移动客户端，从而授予对 Realtime API 的访问权限，而无需 -泄露你的主 API 密钥。你可以为每个客户端密钥配置自定义 TTL。 +客户端密钥是短期有效的令牌，可以传递给客户端应用， +例如 Web 前端或移动客户端，从而授予其对 Realtime API 的访问权限，而无需泄露你的主 API 密钥。 +你可以为每个客户端密钥配置自定义 TTL。 你还可以将会话配置选项附加到客户端密钥，这些选项将 -应用于使用该客户端密钥创建的任何会话，但也可被 +应用于使用该客户端密钥创建的所有会话，但这些选项也可以被 客户端连接覆盖。 -[了解更多关于通过 WebRTC 使用客户端密钥进行身份验证的信息](/docs/guides/realtime-webrtc). +[了解有关使用客户端密钥通过 WebRTC 进行身份验证的更多信息](/docs/guides/realtime-webrtc). -返回创建的客户端密钥和有效的会话对象。客户端密钥是一个类似 `ek_1234`. +返回创建的客户端密钥和有效的会话对象。客户端密钥是一个字符串，形如 `ek_1234`. ### 请求体参数 - `expires_after: optional object { anchor, seconds }` - 客户端密钥过期的配置。过期是指在此时间之后 - 客户端密钥将不再有效用于创建会话。会话本身可能 - 在开始后继续运行。一个密钥可用于创建多个会话 - 直到其过期。 + 客户端密钥过期的配置。过期指的是在此之后 + 客户端密钥将不再可用于创建会话。一旦开始，会话本身可能会 + 在该时间之后继续进行。单个密钥在过期之前可用于创建多个会话 + 。 - `anchor: optional "created_at"` - 客户端密钥过期的锚点，意味着 `seconds` 将添加到 `created_at` 客户端密钥的时间以生成过期时间戳。目前仅支持 `created_at` 。 + 客户端密钥过期的锚点，意味着 `seconds` 将被添加至客户端密钥 `created_at` 的时间，以生成过期时间戳。目前仅支持 `created_at` 。 - `"created_at"` - `seconds: optional number` - 从锚点到过期的秒数。选择一个介于 `10` 和 `7200` （2小时）之间的值。如果未指定，默认值为600秒（10分钟）。 + 从锚点到过期的秒数。请选择介于 `10` 和 `7200` （2 小时）之间的值。若未指定，默认为 600 秒（10 分钟）。 - `session: optional RealtimeSessionCreateRequest or RealtimeTranscriptionSessionCreateRequest` - 用于客户端密钥的会话配置。选择实时 + 用于客户端密钥的会话配置。请选择实时 会话或转录会话。 - `RealtimeSessionCreateRequest object { type, audio, include, 11 more }` @@ -48,7 +48,7 @@ - `type: "realtime"` - 要创建的会话类型。对于实时 API，始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -74,7 +74,7 @@ - `type: optional "audio/pcm"` - 音频格式。始终 `audio/pcm`. + 音频格式。始终为 `audio/pcm`. - `"audio/pcm"` @@ -84,7 +84,7 @@ - `type: optional "audio/pcmu"` - 音频格式。始终 `audio/pcmu`. + 音频格式。始终为 `audio/pcmu`. - `"audio/pcmu"` @@ -94,19 +94,19 @@ - `type: optional "audio/pcma"` - 音频格式。始终 `audio/pcma`. + 音频格式。始终为 `audio/pcma`. - `"audio/pcma"` - `noise_reduction: optional object { type }` - 输入音频降噪的配置。此选项可设置为 `null` 以关闭。 - 降噪会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提升模型性能。 + 输入音频降噪的配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行过滤。 + 对音频进行过滤可以提高 VAD 和轮次检测的准确率（减少误报），并通过改善对输入音频的感知来提升模型表现。 - `type: optional NoiseReductionType` - 降噪类型。 `near_field` 适用于近距离拾音麦克风，例如耳机； `far_field` 适用于远场麦克风，例如笔记本电脑或会议室麦克风。 + 降噪的类型。 `near_field` 适用于近讲麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本或会议室麦克风。 - `"near_field"` @@ -114,13 +114,13 @@ - `transcription: optional AudioTranscription` - 输入音频转录的配置，默认为关闭，可在开启后设置为 `null` 以关闭。输入音频转录并非模型的原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的参考，而非模型实际听到的内容。客户端可以选择设置转录的语言和提示，这些为转录服务提供了额外的指导。 + 输入音频转录的配置，默认为关闭，可设置为 `null` 以在开启后再次关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步进行，应被视为对输入音频内容的指导，而非模型听到的精确内容。客户端可以可选地设置转录的语言和提示，以为转录服务提供额外的指导。 - `delay: optional "minimal" or "low" or "medium" or 2 more` - 控制模型在输出转录文本之前等待的时间。 - 较高的值可以提高转录准确性，但会增加延迟。 - 仅在 GA Realtime 会话中支持 `gpt-realtime-whisper` 。 + 控制模型在发出转录文本之前等待的时间。 + 较高的值可以提高转录准确率，但会增加延迟。 + 仅在以下场景中支持： `gpt-realtime-whisper` 在 GA Realtime 会话中。 - `"minimal"` @@ -134,27 +134,27 @@ - `keywords: optional array of string` - 用于指导输入音频转录的单词或短语。支持者 `gpt-transcribe` 和 `gpt-live-transcribe`. + 用于指导输入音频转录的单词或短语。支持： `gpt-transcribe` 和 `gpt-live-transcribe`. - `language: optional string` 输入音频的语言。在 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) （例如。 `en`）格式 - 将提高准确性和延迟表现。 + 将提升准确率并降低延迟。 - `languages: optional array of string` - 输入音频的可能语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。支持 `gpt-transcribe` 和 `gpt-live-transcribe`. + 输入音频可能使用的语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。支持以下模型： `gpt-transcribe` 和 `gpt-live-transcribe`. - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项有 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。使用 `gpt-4o-transcribe-diarize` 当你需要带说话人标签的说话人分离时。 + 用于转录的模型。当前可选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。请使用 `gpt-4o-transcribe-diarize` 当你需要带有说话人标签的说话人分离时。 - `string` - `"whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` - 用于转录的模型。当前选项有 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。使用 `gpt-4o-transcribe-diarize` 当你需要带说话人标签的说话人分离时。 + 用于转录的模型。当前可选项为 `whisper-1`, `gpt-transcribe`, `gpt-live-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`，以及 `gpt-realtime-whisper`。请使用 `gpt-4o-transcribe-diarize` 当你需要带有说话人标签的说话人分离时。 - `"whisper-1"` @@ -174,84 +174,84 @@ - `prompt: optional string` - 一个可选文本，用于指导模型的风格或延续之前的音频 + 用于引导模型风格或延续前一段音频的可选文本 片段。 - 对于 `whisper-1`， [提示是一组关键词](/docs/guides/speech-to-text#prompting). - 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），提示是一个自由文本字符串，例如“期待与科技相关的词语”。 - 提示不支持与 `gpt-realtime-whisper` 。 + 对于 `whisper-1`，该 [prompt 是一个关键词列表](/docs/guides/speech-to-text#prompting). + 对于 `gpt-4o-transcribe` 模型（不包括 `gpt-4o-transcribe-diarize`），prompt 为自由文本字符串，例如“expect words related to technology”。 + 以下模型不支持 prompt： `gpt-realtime-whisper` 在 GA Realtime 会话中。 - `turn_detection: optional RealtimeAudioInputTurnDetection or null` - 用于回合检测的配置，可以是服务器端 VAD 或语义 VAD。可以设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可以是 Server VAD 或 Semantic VAD。可将其设置为 `null` 以关闭此功能，此情况下客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更先进，使用话轮检测模型（结合 VAD）来语义评估用户是否已说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”声渐渐减弱，模型将判定话轮结束的概率较低，并等待用户继续说话更长时间。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更为先进，它使用一个轮次检测模型（与 VAD 结合）从语义上判断用户是否已说完，然后根据这一概率动态设置超时时间。例如，如果用户语音在 "uhhm" 处逐渐减弱，模型会给出较低的轮次结束概率评分，并等待更长时间以便用户继续发言。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转录会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` 转录会话，轮次检测必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静默一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静音一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以启用简单的服务端 VAD。 + 轮次检测类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` 如果模型已经在响应，这可能会导致创建响应失败。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `idle_timeout_ms: optional number or null` - 可选超时，超过该时间后会自动触发模型响应。这在 - 用户长时间停顿出乎意料的情况下非常有用，例如电话 - 通话。模型将有效地提示用户基于 - 当前上下文继续对话。 + 可选的超时时间，超过后将自动触发模型响应。这在 + 用户长时间停顿属于意外情况的场景中很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话 + 。 - 该超时值将在最后一段模型响应的音频播放完毕后生效， - 即设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在上一个模型响应的音频播放结束后开始计时， + 即其设置时机为 `response.done` time 加上音频播放时长。 - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 与 Response 关联的事件）将在超时达到时触发。 + 一个 `input_audio_buffer.timeout_triggered` event（以及与 Response 关联的事件 + ）将在达到超时时间时发出。 空闲超时目前仅支持 `server_vad` 模式。 - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断（取消）任何正在进行的、输出到默认 - 对话（即。 `conversation` 的 `auto`）的响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + 当 VAD 开始事件发生时，是否自动中断（取消）默认 + 对话（即。 `conversation` 的 `auto`）的任何正在进行且有输出的响应。如果为 `true` ，那么该响应将被取消；否则将一直继续直到完成。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（单位 + 毫秒）。默认为 300 毫秒。 - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音时长（以毫秒为单位）。默认 - 为 500 毫秒。较短的数值会使模型响应更快， - 但可能会在用户的短暂停顿中插入。 + 仅用于 `server_vad` 模式。检测语音停止的静音持续时长（单位为毫秒）。默认为 + 500 毫秒。使用较短的值时，模型响应会更快， + 但可能会在用户的短暂停顿中插话。 - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈 - 值越高，需要更大的音频才能激活模型， - 因此可能在嘈杂环境中表现更好。 + 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认值为 0.5。更高的阈值要求更大的声音才能激活模型， + 因此在嘈杂环境中可能会有更好的表现， + 从而在嘈杂环境中可能表现更好。 - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义轮次检测，使用模型判断用户是否已说完话。 + 服务端语义轮次检测，使用模型来判断用户何时结束说话。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + 轮次检测类型， `semantic_vad` 来开启 Semantic VAD。 - `"semantic_vad"` @@ -261,7 +261,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 将等待用户更长时间继续说话， `high` 将更快响应。 `auto` 为默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + 仅用于 `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以让用户继续说话， `high` 响应更快。 `auto` 是默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -273,8 +273,8 @@ - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断任何正在进行的响应，并将输出发送到默认 - 对话（即。 `conversation` 的 `auto`) 媒体通道。 + 是否在检测到 VAD 开始事件时，使用输出自动中断任何正在进行的响应，并切换到默认 + 对话（即。 `conversation` 的 `auto`)，当 VAD 开始事件发生时。 - `output: optional RealtimeAudioConfigOutput` @@ -284,20 +284,20 @@ - `speed: optional number` - 模型口语响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口头响应速度相对于原始速度的倍数。 + 1.0 为默认速度，0.25 为最低速度，1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 - 此参数是在音频生成后的后处理调整， + 此参数是对生成后音频的后期处理调整，它 也可以提示模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more or object { id }` - 模型用于响应的声音。支持的内置声音包括 + 模型用于响应的语音。支持的内置语音包括 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, - `marin`，以及 `cedar`。你也可以提供带有 - 一个 `id`，字段的自定义声音对象，例如 `{ "id": "voice_1234" }`。声音无法更改 - 在会话期间，只要模型至少回复了一次音频。 - 我们建议 `marin` 和 `cedar` 以获得最佳质量。 + `marin`，以及 `cedar`。你也可以使用 + 一个 `id`，提供自定义语音对象，例如 `{ "id": "voice_1234" }`。语音无法更改 + 只要模型至少响应过一次音频，会话期间便会持续生效。 + 我们建议 `marin` 和 `cedar` 以获得最佳效果。 - `string` @@ -333,24 +333,24 @@ - `include: optional array of "item.input_audio_transcription.logprobs"` - 要包含在服务端输出中的附加字段。 + 包含在服务端输出中的其他字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:在输入音频转录中包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 默认的系统指令（即系统消息），会前置到模型调用中。此字段允许客户端引导模型产生期望的响应。可以指示模型响应的内容和格式（例如“尽量简洁”“表现得友好”“这里有一些好的响应示例”），以及音频行为（例如“说话快一点”“在声音中注入情感”“经常笑”）。模型不保证一定会遵循这些指令，但它们为模型提供了期望行为的指引。 + 预置于模型调用前的默认系统指令（即系统消息）。该字段允许客户端引导模型输出期望的响应。可以指示模型回复内容和格式（例如“极其简洁”、“表现得友好一些”、“以下是较好的回复示例”），以及音频行为（例如“说话快速”、“在声音中注入情感”、“经常大笑”）。指令不一定会被模型严格遵循，但可为模型提供期望行为的指导。 - 请注意，服务端会设置默认指令；如果未设置此字段，将使用这些默认指令，它们会显示在会话开始时的 `session.created` 事件中。 + 请注意，服务端会设置默认指令，当该字段未设置时会使用这些默认指令，这些指令可在会话开始时的 `session.created` 事件中查看。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供 1 到 4096 之间的整数以 - 限制输出 token，或者使用 `inf` 以使用某个 - 给定模型的可用最大 token 数。默认为 `inf`. + 单次助手响应所允许的最大输出 token 数， + 包含工具调用。请提供 1 到 4096 之间的整数以 + 限制输出 token，或者 `inf` 使用指定模型可用的最大 + token 数。默认值为 `inf`. - `number` @@ -360,13 +360,13 @@ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -408,9 +408,9 @@ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将使用音频加转录文本来响应。 `["text"]` 可用于使 - 模型仅以文本响应。无法同时请求 `text` 和 `audio` 两者。 + 模型可以响应的模态集合。默认为 `["audio"]`，表示 + 模型将同时以音频和转录文本进行响应。 `["text"]` 可用于使 + 模型仅以文本进行响应。无法同时请求两者 `text` 和 `audio` 。 - `"text"` @@ -419,7 +419,7 @@ - `parallel_tool_calls: optional boolean` 模型是否可以并行调用多个工具。仅支持 - 推理 Realtime 模型，例如 `gpt-realtime-2`. + reasoning Realtime 模型，例如 `gpt-realtime-2`. - `prompt: optional ResponsePrompt or null` @@ -432,19 +432,19 @@ - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选的值映射，用于替换你的 - 提示中的变量。替换值可以是字符串，也可以是其他 - Response 输入类型，如图像或文件。 + 要在你的 + 提示中替换的变量的可选值映射。替换值可以是字符串，也可以是其他 + Response 输入类型，例如图像或文件。 - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `text: string` - 对模型的文本输入。 + 模型的文本输入。 - `type: "input_text"` @@ -454,7 +454,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -464,11 +464,11 @@ - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + 模型的图像输入。了解 [图像输入](/docs/guides/vision). - `detail: ImageDetail` - 发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`，或 `original`。默认为 `auto`. + 要发送给模型的图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。默认为 `auto`. - `"low"` @@ -486,15 +486,15 @@ - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，也可以是数据 URL 中的 base64 编码图片。 + 要发送到模型的图像 URL。完全限定的 URL，或 data URL 中 base64 编码的图像。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -504,7 +504,7 @@ - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的文件输入。 - `type: "input_file"` @@ -514,7 +514,7 @@ - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 会使用高质量渲染，这可能增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 要发送到模型的文件的详细程度。使用 `auto` 可让系统选择详细程度；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 使用量。使用 `low` 可降低渲染成本，或者使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -524,23 +524,23 @@ - `file_data: optional string` - 要发送给模型的文件内容。 + 要发送到模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -554,11 +554,11 @@ - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 具备推理能力的 Realtime 模型（例如 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 限制支持推理的 Realtime 模型（例如 + 限制具备推理能力的 Realtime 模型（例如 `gpt-realtime-2`. - `"minimal"` @@ -573,16 +573,16 @@ - `tool_choice: optional RealtimeToolChoiceConfig` - 模型如何选择工具。提供一种字符串模式，或强制使用特定的 - function/MCP 工具。 + 模型选择工具的方式。提供字符串模式之一，或强制指定某个 + 函数/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型调用哪个工具（如果有的话）。 + 控制模型调用哪个工具（如果有）。 `none` 表示模型不会调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个工具之间进行选择 + `auto` 表示模型可以在生成消息与调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -595,7 +595,7 @@ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可以强制模型调用指定的函数。 - `name: string` @@ -609,7 +609,7 @@ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可以强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -633,8 +633,8 @@ - `description: optional string` - 函数的描述，包括何时以及如何调用 - 的指导，以及调用时该告知用户什么 + 函数的描述，包括何时以及如何 + 调用它的指引，以及在调用时应如何告知用户的指引 （如果有）。 - `name: optional string` @@ -643,7 +643,7 @@ - `parameters: optional unknown` - JSON Schema 中的函数参数。 + 以 JSON Schema 表示的函数参数。 - `type: optional "function"` @@ -653,8 +653,8 @@ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供额外工具。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol（MCP）服务器为模型提供访问额外工具的能力 + （MCP）服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -662,7 +662,7 @@ - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -676,21 +676,21 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或筛选器对象。 + 允许的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -698,26 +698,26 @@ - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，可通过 - 自定义 MCP 服务器 URL 或服务连接器使用。你的应用程序 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可用于远程 MCP 服务器的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，例如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。了解更多 - 关于服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的那些。必须提供以下之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器的 [信息](/docs/guides/tools-remote-mcp#connectors). - 当前支持的 `connector_id` 值为： + 目前支持的值如下： `connector_id` 目前支持的值如下： - - Dropbox： `connector_dropbox` + - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -737,32 +737,32 @@ - `defer_loading: optional boolean` - 该 MCP 工具是否延迟并通过工具搜索发现。 + 该 MCP 工具是否延迟加载，并通过工具搜索发现。 - `headers: optional map[string] or null` - 要发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的筛选器对象 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`，或与需要审批的工具关联的过滤对象 。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -770,13 +770,13 @@ - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -784,7 +784,7 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 + 为所有工具指定统一的审批策略。可选值为 `always` 或 `never`。当设置为 `always`，时，所有工具都需要审批。当 设置为 `never`，时，所有工具都不需要审批。 @@ -798,60 +798,60 @@ - `server_url: optional string` - MCP 服务器的 URL。必须提供以下之一： `server_url`, `connector_id`，或 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `tunnel_id: optional string` - 安全 MCP 隧道 ID，用于替代直接服务器 URL。必须提供以下之一： + 用于代替直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `tracing: optional RealtimeTracingConfig or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用了 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入到 [追踪仪表板](https://platform.openai.com/logs?api=traces). 设为 null 以禁用追踪。一旦为某个会话启用了 + 追踪,配置便无法再修改。 - `auto` 将为会话创建一个使用默认值的 追踪，其中包含 - 工作流 名称、组 ID 和元数据。 + `auto` 将为该会话创建一个追踪,并使用默认值填充 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. + 启用追踪并为追踪配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 追踪 的精细配置。 + 对追踪的细粒度配置。 - `group_id: optional string` - 附加到此 追踪 的组 ID，用于启用筛选和 - 在追踪仪表盘中进行分组。 + 附加到此追踪的 group id,用于在 + 追踪仪表板中进行筛选和分组。 - `metadata: optional unknown` - 附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的筛选。 + 附加到此追踪的任意元数据,用于在追踪仪表板中启用筛选。 + (合并到上一句) - `workflow_name: optional string` - 要附加到此 工作流 的名称 追踪。这用于 - 在追踪仪表盘中为 追踪 命名。 + 附加到此追踪的工作流名称。该名称用于 + 在追踪仪表板中命名此追踪。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数量超过模型的输入令牌限制时，对话将被截断，这意味着消息（从最早的开始）将不会包含在模型的上下文中。一个 32k 上下文模型，具有 4,096 个最大输出令牌，在发生截断之前只能在上下文中包含 28,224 个令牌。 + 当对话中的 token 数超过模型的输入 token 上限时,对话将被截断,意味着部分消息(从最早的开始)将不会被纳入模型的上下文。具有 32k 上下文、max output tokens 为 4,096 的模型,在发生截断前上下文中只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用和成本的有效方式。 + 客户端可以配置截断行为,以更低的 max token 限制进行截断,这是控制 token 用量和成本的有效方式。 - 截断将减少下一轮中缓存的令牌数量（破坏缓存），因为消息从上下文开头被丢弃。然而，客户端也可以配置截断，以保留最大上下文大小的一部分内的消息，这将减少未来截断的需求，从而提高缓存利用率。 + 截断会减少下一轮中被缓存的 token 数量(使缓存失效),因为消息会从上下文开头被丢弃。不过,客户端也可以将截断配置为保留最多达到最大上下文一定比例的消息,从而降低后续截断的频率,进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会截断，但如果对话超过模型的输入 token 上限，则会返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超过输入 token 上限时发出错误。 - `"auto"` @@ -859,11 +859,11 @@ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多个轮次中分摊截断，有助于改善缓存令牌的使用。 + 当对话超过输入 token 上限时，保留一定比例的对话 token。这允许你在多个轮次之间分摊截断，有助于提升缓存 token 的利用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，要保留的指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的80%。这有助于减少截断频率并提高缓存命中率。 + 超出输入 token 上限时，要保留的指令后对话 token 的比例（`0.0` - `1.0`）。当对话超过输入 token 上限，设置该值为 `0.8` 会一直丢弃消息，直到已使用 token 达到最大允许 token 的 80%。这有助于降低截断频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -873,19 +873,19 @@ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，则使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后（包括工具定义）对话中允许的最大令牌数。例如，将其设置为5,000意味着当对话在指令后超过5,000个令牌时会发生截断。这不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令后对话中允许的最大 token 数（包括工具定义）。例如，将其设置为 5,000 意味着当指令后对话超过 5,000 token 时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出 token 数。 - `RealtimeTranscriptionSessionCreateRequest object { type, audio, include }` - 实时转录会话对象配置。 + 实时转写会话对象配置。 - `type: "transcription"` - 要创建的会话类型。对于实时 API，始终为 `transcription` 用于转录会话。 + 要创建的会话类型。对于 Realtime API，始终为 `transcription` 用于转写会话。 - `"transcription"` @@ -901,90 +901,90 @@ - `noise_reduction: optional object { type }` - 输入音频降噪的配置。此选项可设置为 `null` 以关闭。 - 降噪会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提升模型性能。 + 输入音频降噪的配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行过滤。 + 对音频进行过滤可以提高 VAD 和轮次检测的准确率（减少误报），并通过改善对输入音频的感知来提升模型表现。 - `type: optional NoiseReductionType` - 降噪类型。 `near_field` 适用于近距离拾音麦克风，例如耳机； `far_field` 适用于远场麦克风，例如笔记本电脑或会议室麦克风。 + 降噪的类型。 `near_field` 适用于近讲麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本或会议室麦克风。 - `transcription: optional AudioTranscription` - 输入音频转录的配置，默认为关闭，可在开启后设置为 `null` 以关闭。输入音频转录并非模型的原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的参考，而非模型实际听到的内容。客户端可以选择设置转录的语言和提示，这些为转录服务提供了额外的指导。 + 输入音频转录的配置，默认为关闭，可设置为 `null` 以在开启后再次关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步进行，应被视为对输入音频内容的指导，而非模型听到的精确内容。客户端可以可选地设置转录的语言和提示，以为转录服务提供额外的指导。 - `turn_detection: optional RealtimeTranscriptionSessionAudioInputTurnDetection or null` - 用于回合检测的配置，可以是服务器端 VAD 或语义 VAD。可以设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可以是 Server VAD 或 Semantic VAD。可将其设置为 `null` 以关闭此功能，此情况下客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更先进，使用话轮检测模型（结合 VAD）来语义评估用户是否已说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”声渐渐减弱，模型将判定话轮结束的概率较低，并等待用户继续说话更长时间。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更为先进，它使用一个轮次检测模型（与 VAD 结合）从语义上判断用户是否已说完，然后根据这一概率动态设置超时时间。例如，如果用户语音在 "uhhm" 处逐渐减弱，模型会给出较低的轮次结束概率评分，并等待更长时间以便用户继续发言。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转录会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` 转录会话，轮次检测必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静默一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静音一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以启用简单的服务端 VAD。 + 轮次检测类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` 如果模型已经在响应，这可能会导致创建响应失败。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `idle_timeout_ms: optional number or null` - 可选超时，超过该时间后会自动触发模型响应。这在 - 用户长时间停顿出乎意料的情况下非常有用，例如电话 - 通话。模型将有效地提示用户基于 - 当前上下文继续对话。 + 可选的超时时间，超过后将自动触发模型响应。这在 + 用户长时间停顿属于意外情况的场景中很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话 + 。 - 该超时值将在最后一段模型响应的音频播放完毕后生效， - 即设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在上一个模型响应的音频播放结束后开始计时， + 即其设置时机为 `response.done` time 加上音频播放时长。 - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 与 Response 关联的事件）将在超时达到时触发。 + 一个 `input_audio_buffer.timeout_triggered` event（以及与 Response 关联的事件 + ）将在达到超时时间时发出。 空闲超时目前仅支持 `server_vad` 模式。 - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断（取消）任何正在进行的、输出到默认 - 对话（即。 `conversation` 的 `auto`）的响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + 当 VAD 开始事件发生时，是否自动中断（取消）默认 + 对话（即。 `conversation` 的 `auto`）的任何正在进行且有输出的响应。如果为 `true` ，那么该响应将被取消；否则将一直继续直到完成。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（单位 + 毫秒）。默认为 300 毫秒。 - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音时长（以毫秒为单位）。默认 - 为 500 毫秒。较短的数值会使模型响应更快， - 但可能会在用户的短暂停顿中插入。 + 仅用于 `server_vad` 模式。检测语音停止的静音持续时长（单位为毫秒）。默认为 + 500 毫秒。使用较短的值时，模型响应会更快， + 但可能会在用户的短暂停顿中插话。 - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈 - 值越高，需要更大的音频才能激活模型， - 因此可能在嘈杂环境中表现更好。 + 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认值为 0.5。更高的阈值要求更大的声音才能激活模型， + 因此在嘈杂环境中可能会有更好的表现， + 从而在嘈杂环境中可能表现更好。 - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义轮次检测，使用模型判断用户是否已说完话。 + 服务端语义轮次检测，使用模型来判断用户何时结束说话。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + 轮次检测类型， `semantic_vad` 来开启 Semantic VAD。 - `"semantic_vad"` @@ -994,7 +994,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 将等待用户更长时间继续说话， `high` 将更快响应。 `auto` 为默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + 仅用于 `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以让用户继续说话， `high` 响应更快。 `auto` 是默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -1006,34 +1006,34 @@ - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断任何正在进行的响应，并将输出发送到默认 - 对话（即。 `conversation` 的 `auto`) 媒体通道。 + 是否在检测到 VAD 开始事件时，使用输出自动中断任何正在进行的响应，并切换到默认 + 对话（即。 `conversation` 的 `auto`)，当 VAD 开始事件发生时。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 要包含在服务端输出中的附加字段。 + 包含在服务端输出中的其他字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:在输入音频转录中包含 logprobs。 - `"item.input_audio_transcription.logprobs"` -### 返回 +### Returns - `expires_at: number` - 客户端密钥的过期时间戳，以自纪元以来的秒数表示。 + 客户端密钥的过期时间戳，以自纪元起的秒数表示。 - `session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse` - 会话的配置，适用于实时会话或转录会话。 + 实时会话或转录会话的会话配置。 - `RealtimeSessionCreateResponse object { id, object, type, 13 more }` - 一个实时会话配置对象。 + Realtime 会话配置对象。 - `id: string` - 会话的唯一标识符，格式类似于 `sess_1234567890abcdef`. + 会话的唯一标识符，形如 `sess_1234567890abcdef`. - `object: "realtime.session"` @@ -1043,7 +1043,7 @@ - `type: "realtime"` - 要创建的会话类型。对于实时 API，始终为 `realtime` 。 + 要创建的会话类型。对于 Realtime API，始终为 `realtime` 。 - `"realtime"` @@ -1069,7 +1069,7 @@ - `type: optional "audio/pcm"` - 音频格式。始终 `audio/pcm`. + 音频格式。始终为 `audio/pcm`. - `"audio/pcm"` @@ -1079,7 +1079,7 @@ - `type: optional "audio/pcmu"` - 音频格式。始终 `audio/pcmu`. + 音频格式。始终为 `audio/pcmu`. - `"audio/pcmu"` @@ -1089,19 +1089,19 @@ - `type: optional "audio/pcma"` - 音频格式。始终 `audio/pcma`. + 音频格式。始终为 `audio/pcma`. - `"audio/pcma"` - `noise_reduction: optional object { type }` - 输入音频降噪的配置。此选项可设置为 `null` 以关闭。 - 降噪会过滤添加到输入音频缓冲区中的音频，然后再将其发送到 VAD 和模型。 - 过滤音频可以提高 VAD 和话轮检测的准确性（减少误报），并通过改善对输入音频的感知来提升模型性能。 + 输入音频降噪的配置。可设置为 `null` 以关闭。 + 降噪会在输入音频缓冲区中的音频发送给 VAD 和模型之前对其进行过滤。 + 对音频进行过滤可以提高 VAD 和轮次检测的准确率（减少误报），并通过改善对输入音频的感知来提升模型表现。 - `type: optional NoiseReductionType` - 降噪类型。 `near_field` 适用于近距离拾音麦克风，例如耳机； `far_field` 适用于远场麦克风，例如笔记本电脑或会议室麦克风。 + 降噪的类型。 `near_field` 适用于近讲麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本或会议室麦克风。 - `"near_field"` @@ -1109,7 +1109,7 @@ - `transcription: optional object { language, languages, model, prompt }` - 输入音频转录的配置，默认为关闭，可在开启后设置为 `null` 以关闭。输入音频转录并非模型的原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步运行，应将其视为输入音频内容的参考，而非模型实际听到的内容。客户端可以选择设置转录的语言和提示，这些为转录服务提供了额外的指导。 + 输入音频转录的配置，默认为关闭，可设置为 `null` 以在开启后再次关闭。输入音频转录并非模型原生功能，因为模型直接消费音频。转录通过 [/audio/transcriptions 端点](/docs/api-reference/audio/createTranscription) 异步进行，应被视为对输入音频内容的指导，而非模型听到的精确内容。客户端可以可选地设置转录的语言和提示，以为转录服务提供额外的指导。 - `language: optional string` @@ -1117,7 +1117,7 @@ - `languages: optional array of string` - 为转录配置的可能输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 + 为转录配置的输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` @@ -1147,80 +1147,80 @@ - `prompt: optional string` - 为输入音频转录配置的提示词，如果存在的话。 + 在存在时为输入音频转录配置的提示词。 - `turn_detection: optional object { type, create_response, idle_timeout_ms, 4 more } or object { type, create_response, eagerness, interrupt_response } or null` - 用于回合检测的配置，可以是服务器端 VAD 或语义 VAD。可以设置为 `null` 以关闭，此时客户端必须手动触发模型响应。 + 轮次检测的配置，可以是 Server VAD 或 Semantic VAD。可将其设置为 `null` 以关闭此功能，此情况下客户端必须手动触发模型响应。 - 服务端 VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时做出响应。 + Server VAD 意味着模型将根据音频音量检测语音的开始和结束，并在用户语音结束时进行响应。 - 语义 VAD 更先进，使用话轮检测模型（结合 VAD）来语义评估用户是否已说完，然后根据该概率动态设置超时。例如，如果用户音频以“嗯”声渐渐减弱，模型将判定话轮结束的概率较低，并等待用户继续说话更长时间。这有助于实现更自然的对话，但可能会带来更高的延迟。 + Semantic VAD 更为先进，它使用一个轮次检测模型（与 VAD 结合）从语义上判断用户是否已说完，然后根据这一概率动态设置超时时间。例如，如果用户语音在 "uhhm" 处逐渐减弱，模型会给出较低的轮次结束概率评分，并等待更长时间以便用户继续发言。这对于更自然的对话很有用，但可能会带来更高的延迟。 - 对于 `gpt-realtime-whisper` 转录会话中，话轮检测必须 + 对于 `gpt-realtime-whisper` 转录会话，轮次检测必须 设置为 `null`；不支持 VAD。 - `ServerVad object { type, create_response, idle_timeout_ms, 4 more }` - 服务端语音活动检测（VAD），在检测到用户语音时开启，在静默一段时间后关闭。 + 服务端语音活动检测（VAD），在检测到用户语音时开启，并在静音一段时间后关闭。 - `type: "server_vad"` - 话轮检测类型， `server_vad` 以启用简单的服务端 VAD。 + 轮次检测类型， `server_vad` 以开启简单的 Server VAD。 - `"server_vad"` - `create_response: optional boolean` - 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` ，若模型已在响应中，则可能无法创建响应。 + 是否在 VAD 停止事件发生时自动生成响应。如果 `interrupt_response` 设置为 `false` 如果模型已经在响应，这可能会导致创建响应失败。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `idle_timeout_ms: optional number or null` - 可选超时，超过该时间后会自动触发模型响应。这在 - 用户长时间停顿出乎意料的情况下非常有用，例如电话 - 通话。模型将有效地提示用户基于 - 当前上下文继续对话。 + 可选的超时时间，超过后将自动触发模型响应。这在 + 用户长时间停顿属于意外情况的场景中很有用，例如电话 + 通话。模型会根据当前上下文有效地提示用户继续对话 + 。 - 该超时值将在最后一段模型响应的音频播放完毕后生效， - 即设置为 `response.done` 时间加上音频播放时长。 + 该超时值会在上一个模型响应的音频播放结束后开始计时， + 即其设置时机为 `response.done` time 加上音频播放时长。 - 一个 `input_audio_buffer.timeout_triggered` 事件（以及事件 - 与 Response 关联的事件）将在超时达到时触发。 + 一个 `input_audio_buffer.timeout_triggered` event（以及与 Response 关联的事件 + ）将在达到超时时间时发出。 空闲超时目前仅支持 `server_vad` 模式。 - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断（取消）任何正在进行的、输出到默认 - 对话（即。 `conversation` 的 `auto`）的响应。如果 `true` ，则响应将被取消，否则将继续直到完成。 + 当 VAD 开始事件发生时，是否自动中断（取消）默认 + 对话（即。 `conversation` 的 `auto`）的任何正在进行且有输出的响应。如果为 `true` ，那么该响应将被取消；否则将一直继续直到完成。 - 如果两者 `create_response` 和 `interrupt_response` 均设置为 `false`，模型将永远不会自动响应，但仍会发出 VAD 事件。 + 如果两者 `create_response` 和 `interrupt_response` 都设置为 `false`，模型将永远不会自动响应，但 VAD 事件仍会发出。 - `prefix_padding_ms: optional number` - 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + 仅用于 `server_vad` 模式。在 VAD 检测到语音之前要包含的音频量（单位 + 毫秒）。默认为 300 毫秒。 - `silence_duration_ms: optional number` - 仅用于 `server_vad` 模式。检测语音停止的静音时长（以毫秒为单位）。默认 - 为 500 毫秒。较短的数值会使模型响应更快， - 但可能会在用户的短暂停顿中插入。 + 仅用于 `server_vad` 模式。检测语音停止的静音持续时长（单位为毫秒）。默认为 + 500 毫秒。使用较短的值时，模型响应会更快， + 但可能会在用户的短暂停顿中插话。 - `threshold: optional number` - 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认为 0.5。阈 - 值越高，需要更大的音频才能激活模型， - 因此可能在嘈杂环境中表现更好。 + 仅用于 `server_vad` 模式。VAD 的激活阈值（0.0 到 1.0），默认值为 0.5。更高的阈值要求更大的声音才能激活模型， + 因此在嘈杂环境中可能会有更好的表现， + 从而在嘈杂环境中可能表现更好。 - `SemanticVad object { type, create_response, eagerness, interrupt_response }` - 服务端语义轮次检测，使用模型判断用户是否已说完话。 + 服务端语义轮次检测，使用模型来判断用户何时结束说话。 - `type: "semantic_vad"` - 话轮检测类型， `semantic_vad` 以开启语义 VAD。 + 轮次检测类型， `semantic_vad` 来开启 Semantic VAD。 - `"semantic_vad"` @@ -1230,7 +1230,7 @@ - `eagerness: optional "low" or "medium" or "high" or "auto"` - 仅用于 `semantic_vad` 模式。模型响应的急切程度。 `low` 将等待用户更长时间继续说话， `high` 将更快响应。 `auto` 为默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 + 仅用于 `semantic_vad` 模式。模型响应的积极程度。 `low` 会等待更长时间以让用户继续说话， `high` 响应更快。 `auto` 是默认值，等同于 `medium`. `low`, `medium`，以及 `high` 的最大超时时间分别为 8 秒、4 秒和 2 秒。 - `"low"` @@ -1242,8 +1242,8 @@ - `interrupt_response: optional boolean` - 是否在 VAD 开始事件发生时自动中断任何正在进行的响应，并将输出发送到默认 - 对话（即。 `conversation` 的 `auto`) 媒体通道。 + 是否在检测到 VAD 开始事件时，使用输出自动中断任何正在进行的响应，并切换到默认 + 对话（即。 `conversation` 的 `auto`)，当 VAD 开始事件发生时。 - `output: optional object { format, speed, voice }` @@ -1253,17 +1253,17 @@ - `speed: optional number` - 模型口语响应的速度，以原始速度的倍数表示。 - 1.0 是默认速度。0.25 是最小速度。1.5 是最大速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 + 模型口头响应速度相对于原始速度的倍数。 + 1.0 为默认速度，0.25 为最低速度，1.5 为最高速度。此值只能在模型轮次之间更改，不能在响应进行中更改。 - 此参数是在音频生成后的后处理调整， + 此参数是对生成后音频的后期处理调整，它 也可以提示模型说得更快或更慢。 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。在模型至少响应过一次音频后，语音无法在会话期间更改。当前 - 语音选项为 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + 模型用于回复的声音。一旦模型至少回复过一次音频， + 会话期间就无法再更改声音。当前 + 声音选项包括 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 @@ -1271,9 +1271,9 @@ - `"alloy" or "ash" or "ballad" or 7 more` - 模型用于响应的语音。在模型至少响应过一次音频后，语音无法在会话期间更改。当前 - 语音选项为 - 语音选项为 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, + 模型用于回复的声音。一旦模型至少回复过一次音频， + 会话期间就无法再更改声音。当前 + 声音选项包括 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`，以及 `cedar`。我们推荐 `marin` 和 `cedar` 以获得 最佳质量。 @@ -1299,28 +1299,28 @@ - `expires_at: optional number` - 会话的过期时间戳，以自纪元以来的秒数表示。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 要包含在服务端输出中的附加字段。 + 包含在服务端输出中的其他字段。 - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + `item.input_audio_transcription.logprobs`:在输入音频转录中包含 logprobs。 - `"item.input_audio_transcription.logprobs"` - `instructions: optional string` - 默认的系统指令（即系统消息），会前置到模型调用中。此字段允许客户端引导模型产生期望的响应。可以指示模型响应的内容和格式（例如“尽量简洁”“表现得友好”“这里有一些好的响应示例”），以及音频行为（例如“说话快一点”“在声音中注入情感”“经常笑”）。模型不保证一定会遵循这些指令，但它们为模型提供了期望行为的指引。 + 预置于模型调用前的默认系统指令（即系统消息）。该字段允许客户端引导模型输出期望的响应。可以指示模型回复内容和格式（例如“极其简洁”、“表现得友好一些”、“以下是较好的回复示例”），以及音频行为（例如“说话快速”、“在声音中注入情感”、“经常大笑”）。指令不一定会被模型严格遵循，但可为模型提供期望行为的指导。 - 请注意，服务端会设置默认指令；如果未设置此字段，将使用这些默认指令，它们会显示在会话开始时的 `session.created` 事件中。 + 请注意，服务端会设置默认指令，当该字段未设置时会使用这些默认指令，这些指令可在会话开始时的 `session.created` 事件中查看。 - `max_output_tokens: optional number or "inf"` - 单个助手响应的最大输出 token 数， - 包括工具调用。提供 1 到 4096 之间的整数以 - 限制输出 token，或者使用 `inf` 以使用某个 - 给定模型的可用最大 token 数。默认为 `inf`. + 单次助手响应所允许的最大输出 token 数， + 包含工具调用。请提供 1 到 4096 之间的整数以 + 限制输出 token，或者 `inf` 使用指定模型可用的最大 + token 数。默认值为 `inf`. - `number` @@ -1330,13 +1330,13 @@ - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `string` - `"gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more` - 用于此会话的 Realtime 模型。 + 此会话使用的 Realtime 模型。 - `"gpt-realtime"` @@ -1378,9 +1378,9 @@ - `output_modalities: optional array of "text" or "audio"` - 模型可以响应的模态集合。默认值为 `["audio"]`，表示 - 模型将使用音频加转录文本来响应。 `["text"]` 可用于使 - 模型仅以文本响应。无法同时请求 `text` 和 `audio` 两者。 + 模型可以响应的模态集合。默认为 `["audio"]`，表示 + 模型将同时以音频和转录文本进行响应。 `["text"]` 可用于使 + 模型仅以文本进行响应。无法同时请求两者 `text` 和 `audio` 。 - `"text"` @@ -1397,19 +1397,19 @@ - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null` - 可选的值映射，用于替换你的 - 提示中的变量。替换值可以是字符串，也可以是其他 - Response 输入类型，如图像或文件。 + 要在你的 + 提示中替换的变量的可选值映射。替换值可以是字符串，也可以是其他 + Response 输入类型，例如图像或文件。 - `string` - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 对模型的文本输入。 + 模型的文本输入。 - `text: string` - 对模型的文本输入。 + 模型的文本输入。 - `type: "input_text"` @@ -1419,7 +1419,7 @@ - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -1429,11 +1429,11 @@ - `ResponseInputImage object { detail, type, file_id, 2 more }` - 对模型的图像输入。了解 [图像输入](/docs/guides/vision). + 模型的图像输入。了解 [图像输入](/docs/guides/vision). - `detail: ImageDetail` - 发送给模型的图像的细节级别。可以是 `high`, `low`, `auto`，或 `original`。默认为 `auto`. + 要发送给模型的图像的细节级别。可选值为 `high`, `low`, `auto`，或 `original`。默认为 `auto`. - `"low"` @@ -1451,15 +1451,15 @@ - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `image_url: optional string or null` - 要发送给模型的图片的 URL。可以是完全限定的 URL，也可以是数据 URL 中的 base64 编码图片。 + 要发送到模型的图像 URL。完全限定的 URL，或 data URL 中 base64 编码的图像。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -1469,7 +1469,7 @@ - `ResponseInputFile object { type, detail, file_data, 4 more }` - 发送给模型的文件输入。 + 模型的文件输入。 - `type: "input_file"` @@ -1479,7 +1479,7 @@ - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的细节级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 会使用高质量渲染，这可能增加输入 token 用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高品质渲染文件。默认为 `auto`. + 要发送到模型的文件的详细程度。使用 `auto` 可让系统选择详细程度；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，这可能会增加输入 token 使用量。使用 `low` 可降低渲染成本，或者使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -1489,23 +1489,23 @@ - `file_data: optional string` - 要发送给模型的文件内容。 + 要发送到模型的文件内容。 - `file_id: optional string or null` - 要发送给模型的文件的 ID。 + 要发送到模型的文件的 ID。 - `file_url: optional string` - 要发送给模型的文件的 URL。 + 要发送到模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 要发送到模型的文件的名称。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可重用提示前缀的确切结束位置。断点继承自请求的 `prompt_cache_options.ttl`；边界不会四舍五入到 token 块。 + 标记可复用提示前缀的确切结束位置。该断点会继承请求的 `prompt_cache_options.ttl`；的 TTL；边界不会对齐到 token 块。 - `mode: "explicit"` @@ -1519,11 +1519,11 @@ - `reasoning: optional RealtimeReasoning` - 针对支持推理的 Realtime 模型（例如 `gpt-realtime-2`. + 具备推理能力的 Realtime 模型（例如 `gpt-realtime-2`. - `effort: optional RealtimeReasoningEffort` - 限制支持推理的 Realtime 模型（例如 + 限制具备推理能力的 Realtime 模型（例如 `gpt-realtime-2`. - `"minimal"` @@ -1538,16 +1538,16 @@ - `tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp` - 模型如何选择工具。提供一种字符串模式，或强制使用特定的 - function/MCP 工具。 + 模型选择工具的方式。提供字符串模式之一，或强制指定某个 + 函数/MCP 工具。 - `ToolChoiceOptions = "none" or "auto" or "required"` - 控制模型调用哪个工具（如果有的话）。 + 控制模型调用哪个工具（如果有）。 `none` 表示模型不会调用任何工具，而是生成一条消息。 - `auto` 表示模型可以在生成消息或调用一个或多个工具之间进行选择 + `auto` 表示模型可以在生成消息与调用一个或 更多工具。 `required` 表示模型必须调用一个或多个工具。 @@ -1560,7 +1560,7 @@ - `ToolChoiceFunction object { name, type }` - 使用此选项强制模型调用特定函数。 + 使用此选项可以强制模型调用指定的函数。 - `name: string` @@ -1574,7 +1574,7 @@ - `ToolChoiceMcp object { server_label, type, name }` - 使用此选项强制模型调用远程 MCP 服务器上的特定工具。 + 使用此选项可以强制模型调用远程 MCP 服务器上的指定工具。 - `server_label: string` @@ -1598,8 +1598,8 @@ - `description: optional string` - 函数的描述，包括何时以及如何调用 - 的指导，以及调用时该告知用户什么 + 函数的描述，包括何时以及如何 + 调用它的指引，以及在调用时应如何告知用户的指引 （如果有）。 - `name: optional string` @@ -1608,7 +1608,7 @@ - `parameters: optional unknown` - JSON Schema 中的函数参数。 + 以 JSON Schema 表示的函数参数。 - `type: optional "function"` @@ -1618,8 +1618,8 @@ - `McpTool object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议 - （MCP）服务器为模型提供额外工具。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol（MCP）服务器为模型提供访问额外工具的能力 + （MCP）服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1627,7 +1627,7 @@ - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -1641,21 +1641,21 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或筛选器对象。 + 允许的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称字符串数组 + 允许的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1663,26 +1663,26 @@ - `authorization: optional string` - 可用于远程 MCP 服务器的 OAuth 访问令牌，可通过 - 自定义 MCP 服务器 URL 或服务连接器使用。你的应用程序 - 必须处理 OAuth 授权流程并在此处提供令牌。 + 可用于远程 MCP 服务器的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 + 必须处理 OAuth 授权流程，并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，例如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。了解更多 - 关于服务连接器 [请参阅此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的那些。必须提供以下之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器的 [信息](/docs/guides/tools-remote-mcp#connectors). - 当前支持的 `connector_id` 值为： + 目前支持的值如下： `connector_id` 目前支持的值如下： - - Dropbox： `connector_dropbox` + - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - - Google 日历： `connector_googlecalendar` - - Google 云端硬盘： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook 日历： `connector_outlookcalendar` - - Outlook 邮件： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -1702,32 +1702,32 @@ - `defer_loading: optional boolean` - 该 MCP 工具是否延迟并通过工具搜索发现。 + 该 MCP 工具是否延迟加载，并通过工具搜索发现。 - `headers: optional map[string] or null` - 要发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 - 或其他目的。 + 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 + 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的筛选器对象 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`，或与需要审批的工具关联的过滤对象 。 - `always: optional object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1735,13 +1735,13 @@ - `never: optional object { read_only, tool_names }` - 用于指定允许哪些工具的筛选器对象。 + 用于指定允许哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器 [标有 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - 则将匹配此筛选器。 + 指示工具是否会修改数据或是否为只读。如果某个 + MCP 服务器被 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 标注，则它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1749,7 +1749,7 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定单一审批策略。可以是 `always` 或 + 为所有工具指定统一的审批策略。可选值为 `always` 或 `never`。当设置为 `always`，时，所有工具都需要审批。当 设置为 `never`，时，所有工具都不需要审批。 @@ -1763,60 +1763,60 @@ - `server_url: optional string` - MCP 服务器的 URL。必须提供以下之一： `server_url`, `connector_id`，或 + MCP 服务器的 URL。需提供以下之一 `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `tunnel_id: optional string` - 安全 MCP 隧道 ID，用于替代直接服务器 URL。必须提供以下之一： + 用于代替直接服务器 URL 的 Secure MCP Tunnel ID。需提供以下之一 `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `tracing: optional "auto" or object { group_id, metadata, workflow_name } or null` - Realtime API 可以将会话追踪写入 [追踪仪表盘](https://platform.openai.com/logs?api=traces)。设置为 null 可禁用 追踪。一旦 - 为会话启用了 追踪，该配置便无法修改。 + Realtime API 可以将会话追踪写入到 [追踪仪表板](https://platform.openai.com/logs?api=traces). 设为 null 以禁用追踪。一旦为某个会话启用了 + 追踪,配置便无法再修改。 - `auto` 将为会话创建一个使用默认值的 追踪，其中包含 - 工作流 名称、组 ID 和元数据。 + `auto` 将为该会话创建一个追踪,并使用默认值填充 + 工作流 名称、group id 和元数据。 - `Auto = "auto"` - 启用 追踪 并为 追踪 配置选项设置默认值。始终 `auto`. + 启用追踪并为追踪配置选项设置默认值。始终 `auto`. - `"auto"` - `TracingConfiguration object { group_id, metadata, workflow_name }` - 追踪 的精细配置。 + 对追踪的细粒度配置。 - `group_id: optional string` - 附加到此 追踪 的组 ID，用于启用筛选和 - 在追踪仪表盘中进行分组。 + 附加到此追踪的 group id,用于在 + 追踪仪表板中进行筛选和分组。 - `metadata: optional unknown` - 附加到此 追踪 的任意元数据，用于启用 - 在追踪仪表盘中的筛选。 + 附加到此追踪的任意元数据,用于在追踪仪表板中启用筛选。 + (合并到上一句) - `workflow_name: optional string` - 要附加到此 工作流 的名称 追踪。这用于 - 在追踪仪表盘中为 追踪 命名。 + 附加到此追踪的工作流名称。该名称用于 + 在追踪仪表板中命名此追踪。 - `truncation: optional RealtimeTruncation` - 当对话中的令牌数量超过模型的输入令牌限制时，对话将被截断，这意味着消息（从最早的开始）将不会包含在模型的上下文中。一个 32k 上下文模型，具有 4,096 个最大输出令牌，在发生截断之前只能在上下文中包含 28,224 个令牌。 + 当对话中的 token 数超过模型的输入 token 上限时,对话将被截断,意味着部分消息(从最早的开始)将不会被纳入模型的上下文。具有 32k 上下文、max output tokens 为 4,096 的模型,在发生截断前上下文中只能包含 28,224 个 token。 - 客户端可以配置截断行为，以较低的最大令牌限制进行截断，这是控制令牌使用和成本的有效方式。 + 客户端可以配置截断行为,以更低的 max token 限制进行截断,这是控制 token 用量和成本的有效方式。 - 截断将减少下一轮中缓存的令牌数量（破坏缓存），因为消息从上下文开头被丢弃。然而，客户端也可以配置截断，以保留最大上下文大小的一部分内的消息，这将减少未来截断的需求，从而提高缓存利用率。 + 截断会减少下一轮中被缓存的 token 数量(使缓存失效),因为消息会从上下文开头被丢弃。不过,客户端也可以将截断配置为保留最多达到最大上下文一定比例的消息,从而降低后续截断的频率,进而提升缓存命中率。 - 可以完全禁用截断，这意味着服务器永远不会截断，但如果对话超过模型的输入令牌限制，则会返回错误。 + 可以完全禁用截断，这意味着服务端永远不会截断，但如果对话超过模型的输入 token 上限，则会返回错误。 - `"auto" or "disabled"` - 用于会话的截断策略。 `auto` 是默认的截断策略。 `disabled` 将在对话超过输入令牌限制时禁用截断并发出错误。 + 会话使用的截断策略。 `auto` 是默认的截断策略。 `disabled` 会禁用截断，并在对话超过输入 token 上限时发出错误。 - `"auto"` @@ -1824,11 +1824,11 @@ - `RetentionRatioTruncation object { retention_ratio, type, token_limits }` - 当对话超过输入令牌限制时，保留对话令牌的一部分。这允许你在多个轮次中分摊截断，有助于改善缓存令牌的使用。 + 当对话超过输入 token 上限时，保留一定比例的对话 token。这允许你在多个轮次之间分摊截断，有助于提升缓存 token 的利用率。 - `retention_ratio: number` - 当对话超过输入令牌限制时，要保留的指令后对话令牌的比例（`0.0` - `1.0`）。将其设置为 `0.8` 意味着消息将被丢弃，直到使用最大允许令牌的80%。这有助于减少截断频率并提高缓存命中率。 + 超出输入 token 上限时，要保留的指令后对话 token 的比例（`0.0` - `1.0`）。当对话超过输入 token 上限，设置该值为 `0.8` 会一直丢弃消息，直到已使用 token 达到最大允许 token 的 80%。这有助于降低截断频率并提升缓存命中率。 - `type: "retention_ratio"` @@ -1838,19 +1838,19 @@ - `token_limits: optional object { post_instructions }` - 此截断策略的可选自定义令牌限制。如果未提供，将使用模型的默认令牌限制。 + 此截断策略的可选自定义 token 上限。如果未提供，则使用模型的默认 token 上限。 - `post_instructions: optional number` - 指令后（包括工具定义）对话中允许的最大令牌数。例如，将其设置为5,000意味着当对话在指令后超过5,000个令牌时会发生截断。这不能高于模型的上下文窗口大小减去最大输出令牌数。 + 指令后对话中允许的最大 token 数（包括工具定义）。例如，将其设置为 5,000 意味着当指令后对话超过 5,000 token 时将发生截断。此值不能高于模型的上下文窗口大小减去最大输出 token 数。 - `RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }` - 一个实时转录会话配置对象。 + Realtime 转录会话配置对象。 - `id: string` - 会话的唯一标识符，格式类似于 `sess_1234567890abcdef`. + 会话的唯一标识符，形如 `sess_1234567890abcdef`. - `object: string` @@ -1858,13 +1858,13 @@ - `type: "transcription"` - 会话类型。始终为 `transcription` 用于转录会话。 + 会话的类型。始终为 `transcription` 用于转写会话。 - `"transcription"` - `audio: optional object { input }` - 会话的输入音频配置。 + 该会话的输入音频配置。 - `input: optional object { format, noise_reduction, transcription, turn_detection }` @@ -1878,7 +1878,7 @@ - `type: optional NoiseReductionType` - 降噪类型。 `near_field` 适用于近距离拾音麦克风，例如耳机； `far_field` 适用于远场麦克风，例如笔记本电脑或会议室麦克风。 + 降噪的类型。 `near_field` 适用于近讲麦克风，例如耳机， `far_field` 适用于远场麦克风，例如笔记本或会议室麦克风。 - `transcription: optional object { language, languages, model, prompt }` @@ -1890,7 +1890,7 @@ - `languages: optional array of string` - 为转录配置的可能输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 + 为转录配置的输入音频语言，以 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 格式表示。 - `model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more` @@ -1920,44 +1920,44 @@ - `prompt: optional string` - 为输入音频转录配置的提示词，如果存在的话。 + 在存在时为输入音频转录配置的提示词。 - `turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null` - 话轮检测的配置。可设置为 `null` 以关闭。服务端 - VAD 表示模型将根据 - 音频音量检测语音的开始和结束，并在用户语音结束时响应。对于 `gpt-realtime-whisper`，必须设置为 `null`；不支持 VAD。 + 轮次检测的配置。可设置为 `null` 以关闭。服务端 + VAD 意味着模型将根据 + 音量检测语音的开始和结束，并在用户语音结束时作出响应。对于 `gpt-realtime-whisper`，此项必须为 `null`；不支持 VAD。 - `prefix_padding_ms: optional number` - VAD 检测到语音前要包含的音频量（以 - 毫秒为单位）。默认为 300 毫秒。 + VAD 检测到语音之前包含的音频量（以 + 毫秒）。默认为 300 毫秒。 - `silence_duration_ms: optional number` - 检测语音停止的静音持续时间（以毫秒为单位）。默认 - 为 500 毫秒。较短的数值会使模型响应更快， - 但可能会在用户的短暂停顿中插入。 + 检测语音停止的静音时长（以毫秒为单位）。默认 + 500 毫秒。使用较短的值时，模型响应会更快， + 但可能会在用户的短暂停顿中插话。 - `threshold: optional number` - VAD 的激活阈值（0.0 到 1.0），默认为 0.5。一 - 值越高，需要更大的音频才能激活模型， - 因此可能在嘈杂环境中表现更好。 + VAD 的激活阈值（0.0 到 1.0），默认为 0.5。 + 因此在嘈杂环境中可能会有更好的表现， + 从而在嘈杂环境中可能表现更好。 - `type: optional string` - 话轮检测类型，仅 `server_vad` 。 + 轮次检测的类型，仅限 `server_vad` 。 - `expires_at: optional number` - 会话的过期时间戳，以自纪元以来的秒数表示。 + 会话的过期时间戳，以自纪元起的秒数表示。 - `include: optional array of "item.input_audio_transcription.logprobs"` - 要包含在服务端输出中的附加字段。 + 包含在服务端输出中的其他字段。 - - `item.input_audio_transcription.logprobs`：包含输入音频转录的 logprobs。 + - `item.input_audio_transcription.logprobs`:在输入音频转录中包含 logprobs。 - `"item.input_audio_transcription.logprobs"` diff --git a/docs/zh/api/reference/resources/realtime/translation-client-events.md b/docs/zh/api/reference/resources/realtime/translation-client-events.md index c329d6d..72c50b4 100644 --- a/docs/zh/api/reference/resources/realtime/translation-client-events.md +++ b/docs/zh/api/reference/resources/realtime/translation-client-events.md @@ -1,18 +1,18 @@ -# Realtime 翻译客户端事件 +# 实时翻译客户端事件 -> 完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。可在页面 URL 末尾追加以获取文档页面的 Markdown 版本， `.md` 。 -这些是 OpenAI Realtime Translation WebSocket 服务器将从客户端接受的事件。 +这些是 OpenAI Realtime Translation WebSocket 服务器将接受来自客户端的事件。 ## session.update 发送此事件以更新翻译会话配置。Translation -会话支持对 `audio.output.language`, `audio.input.transcription`, +sessions 支持更新 `audio.output.language`, `audio.input.transcription`, 和 `audio.input.noise_reduction`. ### Schema -Schema 名称： `RealtimeTranslationClientEventSessionUpdate` +Schema name: `RealtimeTranslationClientEventSessionUpdate` ```json { @@ -361,25 +361,25 @@ Schema 名称： `RealtimeTranslationClientEventSessionUpdate` ## session.input_audio_buffer.append -发送此事件以将音频字节追加到翻译会话的输入音频缓冲区。 +发送此事件可将音频字节追加到翻译会话的输入音频缓冲区。 WebSocket 翻译会话接受 base64 编码的 24 kHz PCM16 单声道 -小端原始音频字节。不支持的 WebSocket 音频格式会返回 -验证错误，因为较低质量的音频会显著降低翻译 +小端原始音频字节。不受支持的 WebSocket 音频格式会返回 +校验错误，因为质量较低的音频会显著降低翻译 质量。 -翻译消耗 200 ms 引擎帧。为了获得最佳的实时行为，请以 -200 ms 的块追加音频。如果块较短，服务器会将其缓冲，直到 -有足够的音频组成一帧。如果块较长，服务器会将其拆分为 -200 ms 的帧并连续排队。 +翻译按 200 ms 的引擎帧进行消费。为获得最佳实时效果，请按 +200 ms 的分块追加音频。如果分块较短，服务端会将其缓冲， +直到凑齐一帧音频为止。如果分块较长，服务端会将其拆分为 +200 ms 的帧并依次入队。 -在会话活动期间持续追加静音。如果客户端停止发送 -音频后恢复发送，模型时间会将恢复的音频视为与 -先前音频连续，而不是真实的暂停。 +在会话处于活动状态期间持续追加静音。如果客户端停止发送 +音频后稍后又恢复，模型会将恢复的音频视为与之前的音频连续， +而不是视为真实世界中的停顿。 ### Schema -Schema 名称： `RealtimeTranslationClientEventInputAudioBufferAppend` +Schema name: `RealtimeTranslationClientEventInputAudioBufferAppend` ```json { @@ -486,13 +486,13 @@ Schema 名称： `RealtimeTranslationClientEventInputAudioBufferAppend` ## session.close -优雅关闭实时翻译会话。服务端会在关闭前刷新待处理的 -输入音频并发出所有剩余的翻译输出，然后关闭 -会话。 +优雅地关闭实时翻译会话。服务器会刷新待处理的 +输入音频，并在关闭 +会话之前输出所有剩余的翻译结果。 ### Schema -Schema 名称： `RealtimeTranslationClientEventSessionClose` +Schema name: `RealtimeTranslationClientEventSessionClose` ```json { diff --git a/docs/zh/api/reference/resources/realtime/translation-server-events.md b/docs/zh/api/reference/resources/realtime/translation-server-events.md index 6217d69..a1bfe1c 100644 --- a/docs/zh/api/reference/resources/realtime/translation-server-events.md +++ b/docs/zh/api/reference/resources/realtime/translation-server-events.md @@ -1,18 +1,18 @@ -# 实时翻译服务端事件 +# Realtime 翻译服务端事件 -> 完整文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整的文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾追加 `.md` 即可获得该页面的 Markdown 版本。 -这些是从 OpenAI Realtime Translation WebSocket 服务器发送到客户端的事件。 +这些事件是从 OpenAI Realtime Translation WebSocket 服务器向客户端发送的事件。 -## 错误 +## error -当发生错误时返回，可能是客户端问题或服务器 -问题。大多数错误可恢复且会话将保持打开，我们 -建议实施者默认监控并记录错误消息。 +发生错误时返回，可能是客户端问题或服务端 +问题。大多数错误都是可恢复的，会话将保持打开，建议实现 +者默认监控并记录错误消息。 ### Schema -Schema 名称： `RealtimeServerEventError` +架构名称： `RealtimeServerEventError` ```json { @@ -237,13 +237,13 @@ Schema 名称： `RealtimeServerEventError` ## session.created -当翻译会话创建时返回。当 -新连接建立时自动发出，作为第一个服务器事件。该事件包含 +在创建翻译会话时返回。在建立新连接时作为第一个服务端事件自动发出。该事件包含 默认的翻译会话配置。 +the default translation session configuration. ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionCreated` +架构名称： `RealtimeTranslationServerEventSessionCreated` ```json { @@ -693,12 +693,12 @@ Schema 名称： `RealtimeTranslationServerEventSessionCreated` ## session.updated -当翻译会话更新并带有 `session.update` 事件时返回， -除非出现错误。 +当翻译会话通过 `session.update` 事件更新时返回， +除非发生错误。 ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionUpdated` +架构名称： `RealtimeTranslationServerEventSessionUpdated` ```json { @@ -1148,11 +1148,11 @@ Schema 名称： `RealtimeTranslationServerEventSessionUpdated` ## session.closed -当实时翻译会话关闭时返回。 +实时翻译会话关闭时返回。 ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionClosed` +架构名称： `RealtimeTranslationServerEventSessionClosed` ```json { @@ -1237,15 +1237,15 @@ Schema 名称： `RealtimeTranslationServerEventSessionClosed` ## session.input_transcript.delta -当可选的源语言转录文本可用时返回。此事件 -仅在 `audio.input.transcription` 配置时发出。 +当可选的源语言转写文本可用时返回。该事件 +仅在 `audio.input.transcription` 已配置时才会发出。 -转录增量是仅追加的文本片段。客户端不应在增量之间插入 -无条件空格。 +转写增量是仅追加的文本片段。客户端不应在增量之间 +插入无条件的空格。 ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionInputTranscriptDelta` +架构名称： `RealtimeTranslationServerEventSessionInputTranscriptDelta` ```json { @@ -1370,12 +1370,12 @@ Schema 名称： `RealtimeTranslationServerEventSessionInputTranscriptDelta` 当翻译后的转录文本可用时返回。 -转录增量是仅追加的文本片段。客户端不应在增量之间插入 -无条件空格。 +转写增量是仅追加的文本片段。客户端不应在增量之间 +插入无条件的空格。 ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionOutputTranscriptDelta` +架构名称： `RealtimeTranslationServerEventSessionOutputTranscriptDelta` ```json { @@ -1499,12 +1499,12 @@ Schema 名称： `RealtimeTranslationServerEventSessionOutputTranscriptDelta` ## session.output_audio.delta 当翻译后的输出音频可用时返回。该 `delta` 包含一个 -PCM16 音频块，其长度可能变化。客户端应解码并排队 -完整增量，而不是假设固定的字节或样本数。 +PCM16 音频块，其长度可能会有所不同。客户端应解码并对 +完整的增量进行排队，而不是假定固定的字节数或采样数。 ### Schema -Schema 名称： `RealtimeTranslationServerEventSessionOutputAudioDelta` +架构名称： `RealtimeTranslationServerEventSessionOutputAudioDelta` ```json { diff --git a/docs/zh/api/reference/resources/responses/subresources/input_items/methods/list.md b/docs/zh/api/reference/resources/responses/subresources/input_items/methods/list.md index a404f42..b855d09 100644 --- a/docs/zh/api/reference/resources/responses/subresources/input_items/methods/list.md +++ b/docs/zh/api/reference/resources/responses/subresources/input_items/methods/list.md @@ -1,10 +1,10 @@ -> 完整的文档索引请参见 [llms.txt](/llms.txt)。通过附加在页面 URL 后，可获取文档页面的 Markdown 版本。 `.md` 即可访问。 +> 如需完整文档索引，请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 后追加 `.md` 来获取文档页面的 Markdown 版本。 -## 列出输入条目 +## List input items **get** `/responses/{response_id}/input_items` -返回给定响应的输入项列表。 +返回指定响应的输入项列表。 ### 路径参数 @@ -14,12 +14,12 @@ - `after: optional string` - 用于列出后续项目（分页）的项目 ID。 + 用于分页的项 ID，列出其之后的项。 - `include: optional array of ResponseIncludable` - 响应中包含的附加字段。请参阅 `include` - 上面用于创建 Response 的参数以获取更多信息。 + 响应中要包含的额外字段。详见上文 Response 创建中的 `include` + 参数说明。 - `"file_search_call.results"` @@ -39,25 +39,25 @@ - `limit: optional number` - 返回对象数量的限制。限制范围为 - 1 到 100，默认值为 20。 + 返回对象数量的上限，范围介于 + 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` 返回输入项的顺序。默认为 `desc`. - - `asc`: 按升序返回输入项。 - - `desc`: 按降序返回输入项。 + - `asc`：按升序返回输入项。 + - `desc`：按降序返回输入项。 - `"asc"` - `"desc"` -### 返回 +### Returns - `ResponseItemList object { data, first_id, has_more, 2 more }` - Response 项目列表。 + Response 项目的列表。 - `data: array of ResponseInputMessageItem or ResponseOutputMessage or object { id, queries, status, 2 more } or 26 more` @@ -71,26 +71,26 @@ - `content: ResponseInputMessageContentList` - 一个或多个输入项列表，包含不同类型的内容 + 发送给模型的一个或多个输入项目列表，其中包含不同的内容 类型。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 发送给模型的文本输入。 - `text: string` - 模型的文本输入。 + 发送给模型的文本输入。 - `type: "input_text"` - 输入项的类型。始终为 `input_text`. + 输入项目的类型。始终为 `input_text`. - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示前缀的精确结束位置。断点继承请求的 TTL `prompt_cache_options.ttl`；边界不会四舍五入到令牌块。 + 标记可复用提示词前缀的确切结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会取整到令牌块。 - `mode: "explicit"` @@ -100,11 +100,11 @@ - `ResponseInputImage object { detail, type, file_id, 2 more }` - 模型的图像输入。了解 [图像输入](/docs/guides/vision). + 发送给模型的图像输入。了解 [图像输入](/docs/guides/vision). - `detail: ImageDetail` - 要发送给模型的图像的详细级别。可选值： `high`, `low`, `auto`，或 `original`。默认值： `auto`. + 要发送给模型的图像的详细级别。为以下值之一 `high`, `low`, `auto`，或 `original`。默认为 `auto`. - `"low"` @@ -116,7 +116,7 @@ - `type: "input_image"` - 输入项的类型。始终为 `input_image`. + 输入项目的类型。始终为 `input_image`. - `"input_image"` @@ -126,11 +126,11 @@ - `image_url: optional string or null` - 要发送给模型的图像的 URL。可以是完全限定的 URL，也可以是数据 URL 中的 base64 编码图像。 + 要发送给模型的图像的 URL。完全限定的 URL，或以数据 URL 形式提供的 base64 编码图像。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示前缀的精确结束位置。断点继承请求的 TTL `prompt_cache_options.ttl`；边界不会四舍五入到令牌块。 + 标记可复用提示词前缀的确切结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会取整到令牌块。 - `mode: "explicit"` @@ -140,17 +140,17 @@ - `ResponseInputFile object { type, detail, file_data, 4 more }` - 模型的文件输入。 + 发送给模型的输入文件。 - `type: "input_file"` - 输入项的类型。始终为 `input_file`. + 输入项目的类型。始终为 `input_file`. - `"input_file"` - `detail: optional "auto" or "low" or "high"` - 要发送给模型的文件的详细级别。使用 `auto` 让系统选择细节级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入令牌用量。使用 `low` 进行低成本渲染，或使用 `high` 以更高质量渲染文件。默认为 `auto`. + 要发送给模型的文件的详细级别。使用 `auto` 由系统选择 detail 级别；对于 GPT-5.6 及更高版本的模型， `auto` 使用高质量渲染，可能会增加输入 token 用量。使用 `low` 可以以更低成本渲染，或者使用 `high` 以更高质量渲染文件。默认为 `auto`. - `"auto"` @@ -160,7 +160,7 @@ - `file_data: optional string` - 要发送给模型的文件内容。 + 发送给模型的文件内容。 - `file_id: optional string or null` @@ -168,15 +168,15 @@ - `file_url: optional string` - 要发送给模型的文件的 URL。 + 发送给模型的文件的 URL。 - `filename: optional string` - 要发送给模型的文件的名称。 + 发送给模型的文件名。 - `prompt_cache_breakpoint: optional object { mode }` - 标记可复用提示前缀的精确结束位置。断点继承请求的 TTL `prompt_cache_options.ttl`；边界不会四舍五入到令牌块。 + 标记可复用提示词前缀的确切结束位置。该断点的 TTL 继承自请求的 `prompt_cache_options.ttl`；边界不会取整到令牌块。 - `mode: "explicit"` @@ -186,7 +186,7 @@ - `role: "user" or "system" or "developer"` - 消息输入的角色。可选值包括 `user`, `system`，或 `developer`. + 消息输入的角色。取值为 `user`, `system`，或 `developer`. - `"user"` @@ -202,8 +202,8 @@ - `status: optional "in_progress" or "completed" or "incomplete"` - 项目状态。可选值包括 `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 项的状态。取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -213,7 +213,7 @@ - `ResponseOutputMessage object { id, content, role, 3 more }` - 来自模型的输出消息。 + 模型的一条输出消息。 - `id: string` @@ -225,11 +225,11 @@ - `ResponseOutputText object { annotations, logprobs, text, type }` - 来自模型的文本输出。 + 模型输出的一段文本。 - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - 文本输出的注释。 + 文本输出的注解。 - `FileCitation object { file_id, filename, index, type }` @@ -255,7 +255,7 @@ - `URLCitation object { end_index, start_index, title, 2 more }` - 用于生成模型响应的网络资源的引用。 + 用于生成模型响应的网页资源引用。 - `end_index: number` @@ -267,7 +267,7 @@ - `title: string` - 网络资源的标题。 + 网页资源的标题。 - `type: "url_citation"` @@ -277,11 +277,11 @@ - `url: string` - 网络资源的 URL。 + 网页资源的 URL。 - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - 用于生成模型响应的容器文件的引用。 + 用于生成模型响应的容器文件引用。 - `container_id: string` @@ -297,7 +297,7 @@ - `filename: string` - 所引用的容器文件的文件名。 + 被引用容器文件的文件名。 - `start_index: number` @@ -345,7 +345,7 @@ - `text: string` - 模型的文本输出。 + 模型输出的文本。 - `type: "output_text"` @@ -359,7 +359,7 @@ - `refusal: string` - 模型的拒绝解释。 + 模型的拒绝说明。 - `type: "refusal"` @@ -369,14 +369,14 @@ - `role: "assistant"` - 输出消息的角色。始终 `assistant`. + 输出消息的角色。始终为 `assistant`. - `"assistant"` - `status: "in_progress" or "completed" or "incomplete"` - 消息输入的状态。其中之一 `in_progress`, `completed`，或 - `incomplete`。当输入项通过 API 返回时填充。 + 消息输入的状态。取值为 `in_progress`, `completed`，或 + `incomplete`。之一。当通过 API 返回输入项时填充。 - `"in_progress"` @@ -386,15 +386,15 @@ - `type: "message"` - 输出消息的类型。始终 `message`. + 输出消息的类型。始终为 `message`. - `"message"` - `phase: optional "commentary" or "final_answer" or null` - 将 `assistant` 消息标记为中间评论（`commentary`）或最终答案（`final_answer`). - 对于像 `gpt-5.3-codex` 及更高版本，发送后续请求时，保留并重新发送 - 所有助手消息上的阶段 — 删除它可能会降低性能。不用于用户消息。 + 将一条消息标记为中间评论（ `assistant` 消息的中间评论（`commentary`）或最终答案（`final_answer`). + 对于类似 `gpt-5.3-codex` 及更高版本的模型，在发送后续请求时，请保留并重新发送所有助手消息上的 + 阶段——省略它可能会降低性能。不适用于用户消息。 - `"commentary"` @@ -402,12 +402,12 @@ - `FileSearchCall object { id, queries, status, 2 more }` - 一次 文件搜索 工具调用的结果。参见 - [文件搜索指南](/docs/guides/tools-file-search) 了解更多信息。 + 文件搜索 工具调用的结果。详见 + [文件搜索 指南](/docs/guides/tools-file-search) 以了解更多信息。 - `id: string` - 文件搜索工具调用的唯一ID。 + 文件搜索 工具调用的唯一 ID。 - `queries: array of string` @@ -415,7 +415,7 @@ - `status: "in_progress" or "searching" or "completed" or 2 more` - 文件搜索工具调用的状态。其中之一 `in_progress`, + 文件搜索 工具调用的状态。取值为 `in_progress`, `searching`, `incomplete` 或 `failed`, - `"in_progress"` @@ -430,21 +430,21 @@ - `type: "file_search_call"` - 文件搜索工具调用的类型。始终 `file_search_call`. + 文件搜索 工具调用的类型。始终为 `file_search_call`. - `"file_search_call"` - `results: optional array of object { attributes, file_id, filename, 2 more } or null` - 文件搜索工具调用的结果。 + 文件搜索 工具调用的结果。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组16个键值对。这可以 - 用于以结构化 - 格式存储有关对象的附加信息，并通过API或仪表板查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可以附加到对象的 16 个键值对。可用于 + 可用于以结构化形式存储有关对象的附加信息， + 并通过 API 或控制面板查询对象。键为字符串， + 最大长度为 64 个字符。值为字符串（最大长度 + 为 512 个字符）、布尔值或数字。 - `string` @@ -462,7 +462,7 @@ - `score: optional number` - 文件的相关性分数——介于 0 和 1 之间的值。 + 文件的相关性评分，取值范围为 0 到 1。 - `text: optional string` @@ -470,8 +470,8 @@ - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - 对计算机使用工具的工具调用。请参阅 - [computer use guide](/docs/guides/tools-computer-use) 了解更多信息。 + 对计算机使用工具的工具调用。参阅 + [computer use 指南](/docs/guides/tools-computer-use) 以了解更多信息。 - `id: string` @@ -479,7 +479,7 @@ - `call_id: string` - 用于在响应工具调用时提供输出的标识符。 + 用于在响应工具调用并附带输出时使用的标识符。 - `pending_safety_checks: array of object { id, code, message }` @@ -495,12 +495,12 @@ - `message: optional string or null` - 有关待处理安全检查的详细信息。 + 待处理安全检查的详细信息。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -510,21 +510,21 @@ - `type: "computer_call"` - 计算机调用的类型。始终 `computer_call`. + 计算机调用的类型，始终为 `computer_call`. - `"computer_call"` - `action: optional ComputerAction` - 点击操作。 + 一次点击操作。 - `Click object { button, type, x, 2 more }` - 点击操作。 + 一次点击操作。 - `button: "left" or "right" or "wheel" or 2 more` - 指示点击期间按下了哪个鼠标按钮。以下之一： `left`, `right`, `wheel`, `back`，或 `forward`. + 指示点击时按下的是哪个鼠标按键，取值为 `left`, `right`, `wheel`, `back`，或 `forward`. - `"left"` @@ -544,15 +544,15 @@ - `x: number` - 点击发生的 x 坐标。 + 发生点击的 x 坐标。 - `y: number` - 点击发生的 y 坐标。 + 发生点击的 y 坐标。 - `keys: optional array of string or null` - 点击时按住的按键。 + 点击时按住的键。 - `DoubleClick object { keys, type, x, y }` @@ -560,7 +560,7 @@ - `keys: array of string or null` - 双击时按住的按键。 + 双击时按住的键。 - `type: "double_click"` @@ -570,11 +570,11 @@ - `x: number` - 双击发生的 x 坐标。 + 发生双击的 x 坐标。 - `y: number` - 双击发生的 y 坐标。 + 发生双击的 y 坐标。 - `Drag object { path, type, keys }` @@ -582,7 +582,7 @@ - `path: array of object { x, y }` - 一个坐标数组，表示拖动操作的路径。坐标将以对象数组的形式出现，例如 + 表示拖动操作路径的坐标数组。坐标将作为对象数组显示，例如 ``` [ @@ -607,15 +607,15 @@ - `keys: optional array of string or null` - 拖动鼠标时按住的按键。 + 拖动鼠标时按住的键。 - `Keypress object { keys, type }` - 模型希望执行的按键操作集合。 + 模型希望执行的按键集合。 - `keys: array of string` - 模型请求按下的按键组合。这是一个字符串数组，每个字符串表示一个按键。 + 模型请求按下的键组合。这是一个字符串数组，每个字符串表示一个键。 - `type: "keypress"` @@ -647,17 +647,17 @@ - `Screenshot object { type }` - 截图操作。 + 截图动作。 - `type: "screenshot"` - 指定事件类型。对于截图操作，此属性始终设置为 `screenshot`. + 指定事件类型。对于截图动作，此属性始终设置为 `screenshot`. - `"screenshot"` - `Scroll object { scroll_x, scroll_y, type, 3 more }` - 滚动操作。 + 滚动动作。 - `scroll_x: number` @@ -669,17 +669,17 @@ - `type: "scroll"` - 指定事件类型。对于滚动操作，此属性始终设置为 `scroll`. + 指定事件类型。对于滚动动作，此属性始终设置为 `scroll`. - `"scroll"` - `x: number` - 发生滚动的 x 坐标。 + 发生滚动位置的 x 坐标。 - `y: number` - 发生滚动的 y 坐标。 + 发生滚动位置的 y 坐标。 - `keys: optional array of string or null` @@ -687,7 +687,7 @@ - `Type object { text, type }` - 输入文本的操作。 + 用于输入文本的动作。 - `text: string` @@ -695,28 +695,28 @@ - `type: "type"` - 指定事件类型。对于输入操作，此属性始终设置为 `type`. + 指定事件类型。对于输入动作，此属性始终设置为 `type`. - `"type"` - `Wait object { type }` - 等待操作。 + 等待动作。 - `type: "wait"` - 指定事件类型。对于等待操作，此属性始终设置为 `wait`. + 指定事件类型。对于等待动作，此属性始终设置为 `wait`. - `"wait"` - `actions: optional ComputerActionList` - 展平的批处理操作，用于 `computer_use`。每个操作包括一个 - `type` 判别器和操作特定字段。 + 已展平的批处理动作，适用于 `computer_use`。每个动作都包含一个 + `type` 鉴别字段以及动作特有的字段。 - `Click object { button, type, x, 2 more }` - 点击操作。 + 一次点击操作。 - `DoubleClick object { keys, type, x, y }` @@ -728,7 +728,7 @@ - `Keypress object { keys, type }` - 模型希望执行的按键操作集合。 + 模型希望执行的按键集合。 - `Move object { type, x, y, keys }` @@ -736,33 +736,33 @@ - `Screenshot object { type }` - 截图操作。 + 截图动作。 - `Scroll object { scroll_x, scroll_y, type, 3 more }` - 滚动操作。 + 滚动动作。 - `Type object { text, type }` - 输入文本的操作。 + 用于输入文本的动作。 - `Wait object { type }` - 等待操作。 + 等待动作。 - `ComputerCallOutput object { id, call_id, output, 4 more }` - `id: string` - 计算机调用工具输出的唯一 ID。 + computer call 工具输出的唯一 ID。 - `call_id: string` - 产生该输出的计算机工具调用的 ID。 + 生成该输出的 computer 工具调用的 ID。 - `output: ResponseComputerToolCallOutputScreenshot` - 与计算机使用工具一起使用的计算机截图图像。 + 与 computer use 工具配合使用的计算机截图图像。 - `type: "computer_screenshot"` @@ -773,7 +773,7 @@ - `file_id: optional string` - 包含截图的已上传文件的标识符。 + 包含截图的上传文件的标识符。 - `image_url: optional string` @@ -781,8 +781,8 @@ - `status: "completed" or "incomplete" or "failed" or "in_progress"` - 消息输入的状态。其中之一 `in_progress`, `completed`，或 - `incomplete`。当输入项通过 API 返回时填充。 + 消息输入的状态。取值为 `in_progress`, `completed`，或 + `incomplete`。之一。当通过 API 返回输入项时填充。 - `"completed"` @@ -794,13 +794,13 @@ - `type: "computer_call_output"` - 计算机工具调用输出的类型。始终为 `computer_call_output`. + computer 工具调用输出的类型。始终 `computer_call_output`. - `"computer_call_output"` - `acknowledged_safety_checks: optional array of object { id, code, message }` - API 报告并已由 + API 报告的、已被 开发者确认的安全检查。 - `id: string` @@ -813,33 +813,33 @@ - `message: optional string or null` - 有关待处理安全检查的详细信息。 + 待处理安全检查的详细信息。 - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `WebSearchCall object { id, action, status, type }` - 网页搜索工具调用的结果。参见 - [网页搜索指南](/docs/guides/tools-web-search) 了解更多信息。 + 网页搜索 工具调用的结果。参见 + [网页搜索 指南](/docs/guides/tools-web-search) 以了解更多信息。 - `id: string` - 网页搜索工具调用的唯一 ID。 + 网页搜索 工具调用的唯一 ID。 - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - 描述本次网页搜索调用中采取的具体操作的对象。 - 包括模型如何使用网络（search、open_page、find_in_page）的详细信息。 + 描述此次 网页搜索 调用中所执行的具体操作的对象。 + 包含模型使用网络方式的详细信息（search、open_page、find_in_page）。 - `Search object { type, queries, query, sources }` - 动作类型"search" - 执行网页搜索查询。 + 操作类型 "search" —— 执行 网页搜索 查询。 - `type: "search"` - 动作类型。 + 操作类型。 - `"search"` @@ -849,7 +849,7 @@ - `query: optional string` - 搜索查询。 + 搜索查询内容。 - `sources: optional array of object { type, url }` @@ -871,13 +871,13 @@ - `type: "open_page"` - 动作类型。 + 操作类型。 - `"open_page"` - `url: optional string or null` - 由模型打开的 URL。 + 模型打开的 URL。 - `FindInPage object { pattern, type, url }` @@ -889,17 +889,17 @@ - `type: "find_in_page"` - 动作类型。 + 操作类型。 - `"find_in_page"` - `url: string` - 搜索了该模式的页面的 URL。 + 在其中搜索模式的页面 URL。 - `status: "in_progress" or "searching" or "completed" or "failed"` - 网页搜索 工具调用的状态。 + 网页搜索工具调用的状态。 - `"in_progress"` @@ -911,7 +911,7 @@ - `type: "web_search_call"` - 网页搜索 工具调用的类型。始终为 `web_search_call`. + 网页搜索工具调用的类型。始终为 `web_search_call`. - `"web_search_call"` @@ -923,20 +923,20 @@ - `arguments: string` - 要传递给函数的参数的 JSON 字符串。 + 传递给函数的参数的 JSON 字符串。 - `call_id: string` - 由模型生成的函数工具调用的唯一 ID。 + 模型生成的函数工具调用的唯一 ID。 - `name: string` - 要运行的函数的名称。 + 要运行的函数名称。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -952,7 +952,7 @@ - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -964,7 +964,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -972,11 +972,11 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `namespace: optional string` - 要运行的函数的命名空间。 + 要运行的函数命名空间。 - `FunctionCallOutput object { id, output, status, 6 more }` @@ -986,12 +986,12 @@ - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 由你的代码生成的函数调用的输出。 + 代码生成的函数调用输出。 可以是字符串或输出内容的列表。 - `StringOutput = string` - 函数调用的输出字符串。 + 函数调用输出的字符串。 - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` @@ -999,20 +999,20 @@ - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 发送给模型的文本输入。 - `ResponseInputImage object { detail, type, file_id, 2 more }` - 模型的图像输入。了解 [图像输入](/docs/guides/vision). + 发送给模型的图像输入。了解 [图像输入](/docs/guides/vision). - `ResponseInputFile object { type, detail, file_data, 4 more }` - 模型的文件输入。 + 发送给模型的输入文件。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -1028,11 +1028,11 @@ - `call_id: optional string` - 由模型生成的函数工具调用的唯一 ID。 + 模型生成的函数工具调用的唯一 ID。 - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -1046,7 +1046,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -1056,15 +1056,15 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `name: optional string` - 产生输出的工具名称。 + 生成该输出的工具名称。 - `namespace: optional string` - 产生输出的工具的命名空间。 + 生成该输出的工具命名空间。 - `ToolSearchCall object { id, arguments, call_id, 4 more }` @@ -1074,7 +1074,7 @@ - `arguments: unknown` - 工具搜索调用使用的参数。 + 用于工具搜索调用的参数。 - `call_id: string or null` @@ -1082,7 +1082,7 @@ - `execution: "server" or "client"` - 工具搜索是由服务端执行还是由客户端执行。 + 工具搜索是由服务端还是由客户端执行的。 - `"server"` @@ -1090,7 +1090,7 @@ - `status: "in_progress" or "completed" or "incomplete"` - 记录的工具搜索调用项的状态。 + 已记录的工具搜索调用项的状态。 - `"in_progress"` @@ -1100,13 +1100,13 @@ - `type: "tool_search_call"` - 项的类型。始终为 `tool_search_call`. + 该项的类型。始终为 `tool_search_call`. - `"tool_search_call"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `ToolSearchOutput object { id, call_id, execution, 4 more }` @@ -1120,7 +1120,7 @@ - `execution: "server" or "client"` - 工具搜索是由服务端执行还是由客户端执行。 + 工具搜索是由服务端还是由客户端执行的。 - `"server"` @@ -1128,7 +1128,7 @@ - `status: "in_progress" or "completed" or "incomplete"` - 记录的工具搜索输出项的状态。 + 已记录的工具搜索输出项的状态。 - `"in_progress"` @@ -1142,19 +1142,19 @@ - `Function object { name, parameters, strict, 5 more }` - 定义你代码中模型可选择调用的函数。了解有关 [函数调用](https://platform.openai.com/docs/guides/function-calling). + 在你自己代码中定义一个可由模型选择调用的函数。了解更多关于 [函数调用](https://platform.openai.com/docs/guides/function-calling). - `name: string` - 要调用的函数的名称。 + 要调用的函数名称。 - `parameters: map[unknown] or null` - 描述函数参数的 JSON schema 对象。 + 描述该函数参数的 JSON schema 对象。 - `strict: boolean or null` - 是否对此函数工具强制执行严格参数验证。 + 是否对该函数工具强制执行严格的参数校验。 - `type: "function"` @@ -1172,19 +1172,19 @@ - `defer_loading: optional boolean` - 此函数是否延迟并通过工具搜索加载。 + 该函数是否被延迟加载并通过工具搜索加载。 - `description: optional string or null` - 函数的描述。模型据此决定是否调用该函数。 + 对该函数的描述。供模型用来决定是否调用该函数。 - `output_schema: optional map[unknown] or null` - 一个 JSON schema 对象，描述此函数字符串输出中编码的 JSON 值。 + 用于描述该函数字符串输出中所编码 JSON 值的 JSON schema 对象。 - `FileSearch object { type, vector_store_ids, filters, 2 more }` - 一个从上传文件中搜索相关内容的工具。了解更多关于 [文件搜索 工具](https://platform.openai.com/docs/guides/tools-file-search). + 从已上传文件中搜索相关内容的一款工具。了解更多关于 [文件搜索 工具](https://platform.openai.com/docs/guides/tools-file-search). - `type: "file_search"` @@ -1194,15 +1194,15 @@ - `vector_store_ids: array of string` - 要搜索的向量存储的 ID。 + 要搜索的向量存储 ID。 - `filters: optional ComparisonFilter or CompoundFilter or null` - 要应用的过滤器。 + 要应用的筛选条件。 - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作将指定属性键与给定值进行比较的过滤器。 + 用于将指定的属性键与给定值按定义的比较运算进行比较的筛选器。 - `key: string` @@ -1212,14 +1212,14 @@ 指定比较运算符： `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `eq`：等于 - - `ne`：不等于 - - `gt`：大于 - - `gte`：大于或等于 - - `lt`：小于 - - `lte`：小于或等于 - - `in`：在 - - `nin`：不在 + - `eq`: 等于 + - `ne`: 不等于 + - `gt`: 大于 + - `gte`: 大于或等于 + - `lt`: 小于 + - `lte`: 小于或等于 + - `in`：包含于 + - `nin`：未包含于 - `"eq"` @@ -1239,7 +1239,7 @@ - `value: string or number or boolean or array of string or number` - 要与属性键比较的值；支持字符串、数字或布尔类型。 + 用于与属性键进行比较的值；支持字符串、数字或布尔类型。 - `string` @@ -1255,15 +1255,15 @@ - `CompoundFilter object { filters, type }` - 使用以下方式组合多个过滤器 `and` 或 `or`. + 使用以下方式组合多个筛选器 `and` 或 `or`. - `filters: array of ComparisonFilter or unknown` - 要组合的过滤器数组。项目可以是 `ComparisonFilter` 或 `CompoundFilter`. + 要组合的筛选器数组。各项可以是 `ComparisonFilter` 或 `CompoundFilter`. - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作将指定属性键与给定值进行比较的过滤器。 + 用于将指定的属性键与给定值按定义的比较运算进行比较的筛选器。 - `unknown` @@ -1277,27 +1277,27 @@ - `max_num_results: optional number` - 要返回的最大结果数。此数字应在 1 到 50 之间（含）。 + 返回的最大结果数量。该数值应介于 1 到 50 之间（含端点）。 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 搜索的排名选项。 + 搜索的排序选项。 - `hybrid_search: optional object { embedding_weight, text_weight }` - 当启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。 + 在启用混合搜索时，用于控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡的权重。 - `embedding_weight: number` - 倒数排名融合中嵌入的权重。 + 在倒数排名融合中嵌入向量的权重。 - `text_weight: number` - 倒数排名融合中文本的权重。 + 在倒数排名融合中文本的权重。 - `ranker: optional "auto" or "default-2024-11-15"` - 用于文件搜索的排名器。 + 用于文件搜索的排序器。 - `"auto"` @@ -1305,21 +1305,21 @@ - `score_threshold: optional number` - 文件搜索的分数阈值，一个介于 0 和 1 之间的数字。更接近 1 的数字将尝试仅返回最相关的结果，但可能返回较少的结果。 + 文件搜索的分数阈值，介于 0 到 1 之间的数值。越接近 1 的数值会尝试仅返回相关性最高的结果，但返回的结果数量可能更少。 - `Computer object { type }` - 一个控制虚拟计算机的工具。了解有关 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: "computer"` - 计算机工具的类型。始终为 `computer`. + computer tool 的类型，恒为 `computer`. - `"computer"` - `ComputerUsePreview object { display_height, display_width, environment, type }` - 一个控制虚拟计算机的工具。了解有关 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: number` @@ -1345,18 +1345,18 @@ - `type: "computer_use_preview"` - 计算机使用工具的类型。始终为 `computer_use_preview`. + computer use 工具的类型，恒为 `computer_use_preview`. - `"computer_use_preview"` - `WebSearch object { type, external_web_access, filters, 2 more }` - 搜索互联网以获取与提示相关的来源。详细了解 + 在互联网上搜索与提示相关的来源。详细了解 [网页搜索工具](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` - 网页搜索工具的类型。之一 `web_search` 或 `web_search_2025_08_26`. + 网页搜索工具的类型，取值之一 `web_search` 或 `web_search_2025_08_26`. - `"web_search"` @@ -1364,22 +1364,22 @@ - `external_web_access: optional boolean` - 允许网页搜索进行实时互联网访问。省略时默认为 true。当为 false 时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 + 允许 网页搜索访问实时互联网。省略时默认为 true。当为 false 时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 - `filters: optional object { allowed_domains } or null` - 搜索的过滤器。 + 搜索的筛选条件。 - `allowed_domains: optional array of string or null` - 允许搜索的域名。如果未提供，则允许所有域名。 - 所提供域名的子域名也允许。 + 搜索所允许的域名。如果未提供，则允许所有域名。 + 所提供域名的子域名也同样被允许。 示例： `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。之一 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间的高层级用量指导，取值之一 `low`, `medium`，或 `high`. `medium` 是默认值。 - `"low"` @@ -1393,38 +1393,38 @@ - `city: optional string or null` - 用户城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两位 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) 用户的，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` - 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) 用户的，例如。 `America/Los_Angeles`. + 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) ，例如。 `America/Los_Angeles`. - `type: optional "approximate"` - 位置近似类型。始终 `approximate`. + 位置近似值的类型，始终为 `approximate`. - `"approximate"` - `Mcp object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议为模型提供额外工具 - （MCP）服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol 让模型能够访问其他工具 + (MCP) 服务器。 [详细了解 MCP](/docs/guides/tools-remote-mcp). - `server_label: string` - 此 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中识别该服务器。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -1438,20 +1438,20 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称的字符串数组 + 允许使用的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1460,26 +1460,26 @@ - `authorization: optional string` - 一个 OAuth 访问令牌，可与远程 MCP 服务器一起使用， - 可与自定义 MCP 服务器 URL 或服务连接器一起使用。你的应用程序 + 可与远程 MCP 服务器一起使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 必须处理 OAuth 授权流程并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器的信息 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。其中之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持 `connector_id` 支持的值为： + 当前支持 `connector_id` 值包括： - - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google Calendar： `connector_googlecalendar` - - Google Drive： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook Calendar： `connector_outlookcalendar` - - Outlook Email： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -1499,31 +1499,31 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟发现工具，需通过工具搜索获取。 - `headers: optional map[string] or null` - 要发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 + 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的过滤器对象 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`，也可以是与需要审批的工具关联的过滤器对象 。 - `always: optional object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1532,12 +1532,12 @@ - `never: optional object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -1546,9 +1546,9 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定一个审批策略。可以是 `always` 或 + 为所有工具指定统一的审批策略。可选值为 `always` 或 `never`。之一。当设置为 `always`，时，所有工具都需要审批。当设置为 - 时 `never`，所有工具均无需审批。 + 时 `never`，所有工具都将无需审批。 - `"always"` @@ -1560,23 +1560,23 @@ - `server_url: optional string` - MCP 服务器的 URL。必须提供 `server_url`, `connector_id`，或 - `tunnel_id` 之一。 + MCP 服务器的 URL。以下其中之一 `server_url`, `connector_id`，或 + `tunnel_id` 必须提供。 - `tunnel_id: optional string` - 安全 MCP 隧道 ID，用于替代直接服务器 URL。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。以下其中之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `CodeInterpreter object { container, type, allowed_callers }` - 一个运行 Python 代码以帮助生成提示响应的工具。 + 用于运行 Python 代码以帮助生成针对提示的响应的工具。 - `container: string or object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器。可以是容器 ID 或一个 - 指定上传文件 ID 的对象，以使这些文件可供你的代码使用，并附带 - 可选 `memory_limit` 设置。 + 代码解释器容器。可以是容器 ID，或是指定了可供代码使用的已上传文件 ID 以及一个 + 可选 + 可选 `memory_limit` 设置的对象。 - `string` @@ -1584,7 +1584,7 @@ - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器的配置。可选择指定要运行代码的文件的 ID。 + 代码解释器容器的配置。可选择指定要在其上运行代码的文件 ID。 - `type: "auto"` @@ -1594,7 +1594,7 @@ - `file_ids: optional array of string` - 可选的已上传文件列表，供你的代码使用。 + 可供代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -1628,25 +1628,25 @@ - `type: "allowlist"` - 仅允许对指定域名的出站网络访问。始终 `allowlist`. + 仅允许向指定域进行出站网络访问。始终 `allowlist`. - `"allowlist"` - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - 可选的范围限定于域的密钥，用于允许列表中的域名。 + 针对已加入允许列表的域的可选域范围密钥。 - `domain: string` - 与该密钥关联的域名。 + 与该密钥关联的域。 - `name: string` - 要为该域名注入的密钥名称。 + 为该域注入的密钥名称。 - `value: string` - 要为该域名注入的密钥值。 + 为该域注入的密钥值。 - `type: "code_interpreter"` @@ -1682,7 +1682,7 @@ - `action: optional "generate" or "edit" or "auto"` - 是生成新图像还是编辑现有图像。默认值： `auto`. + 是生成新图像还是编辑已有图像。默认值： `auto`. - `"generate"` @@ -1692,10 +1692,10 @@ - `background: optional "transparent" or "opaque" or "auto"` - 设置生成图像的背景。选项之一： `transparent`, - `opaque`，或 `auto`。透明背景可用于 + 设置生成图像的背景。可选值为 `transparent`, + `opaque`，或 `auto`。透明背景适用于 支持的 GPT 图像模型。对于 `gpt-image-2` 和 - `gpt-image-2-2026-04-21`，此支持处于预览阶段。使用 + `gpt-image-2-2026-04-21`，此支持为预览阶段。使用 `transparent`，时，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. - `"transparent"` @@ -1706,7 +1706,7 @@ - `input_fidelity: optional "high" or "low" or null` - 控制模型在匹配输入图像的风格和特征（尤其是面部特征）方面投入多少努力。此参数仅支持 `gpt-image-1` 和 `gpt-image-1.5` 及更高版本的模型，不支持 `gpt-image-1-mini`。支持 `high` 和 `low`。默认值： `low`. + 控制模型在匹配输入图像的风格和特征（尤其是面部特征）时所投入的精力。此参数仅在 `gpt-image-1` 和 `gpt-image-1.5` 及更高版本模型中受支持，不支持 `gpt-image-1-mini`。支持 `high` 和 `low`。默认为 `low`. - `"high"` @@ -1714,20 +1714,20 @@ - `input_image_mask: optional object { file_id, image_url }` - 用于修复的可选蒙版。包含 `image_url` - （字符串，可选）和 `file_id` （字符串，可选）。 + 用于局部重绘的可选蒙版。包含 `image_url` + （字符串，可选）和 `file_id` (string, optional). - `file_id: optional string` - 掩码图像的文件 ID。 + 掩膜图像的文件 ID。 - `image_url: optional string` - Base64 编码的掩码图像。 + Base64 编码的掩膜图像。 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。之一为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -1736,7 +1736,7 @@ - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。之一为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -1753,7 +1753,7 @@ - `moderation: optional "auto" or "low"` - 生成图像的审核级别。默认值： `auto`. + 生成图像的内容审核级别。默认值： `auto`. - `"auto"` @@ -1765,7 +1765,7 @@ - `output_format: optional "png" or "webp" or "jpeg"` - 生成图像的输出格式。之一为 `png`, `webp`，或 + 生成图像的输出格式。可选值为 `png`, `webp`，或 `jpeg`。默认值： `png`. - `"png"` @@ -1776,11 +1776,11 @@ - `partial_images: optional number` - 在流式模式下生成的部分图像数量，范围为 0（默认值）到 3。 + 在流式模式下生成的部分图像数量，取值范围为 0（默认值）到 3。 - `quality: optional "low" or "medium" or "high" or "auto"` - 生成图像的质量。之一为 `low`, `medium`, `high`, + 生成图像的质量。可选值为 `low`, `medium`, `high`, 或 `auto`。默认值： `auto`. - `"low"` @@ -1793,13 +1793,13 @@ - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`, 以及 `1024x1536` 受 GPT 图像模型支持； `auto` 适用于允许自动调整尺寸的模型。对于 `dall-e-2`，使用以下之一 `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持以 `WIDTHxHEIGHT` 字符串形式指定任意分辨率，例如 `1536x864`。宽度和高度都必须能被 16 整除，并且请求的长宽比必须介于 1:3 和 3:1 之间。超过 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，和 `1024x1536` 由 GPT image 模型支持； `auto` 由支持自动尺寸的模型支持。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。之一。对于 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. - `string` - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`, 以及 `1024x1536` 受 GPT 图像模型支持； `auto` 适用于允许自动调整尺寸的模型。对于 `dall-e-2`，使用以下之一 `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持以 `WIDTHxHEIGHT` 字符串形式指定任意分辨率，例如 `1536x864`。宽度和高度都必须能被 16 整除，并且请求的长宽比必须介于 1:3 和 3:1 之间。超过 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，和 `1024x1536` 由 GPT image 模型支持； `auto` 由支持自动尺寸的模型支持。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。之一。对于 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. - `"1024x1024"` @@ -1811,7 +1811,7 @@ - `LocalShell object { type }` - 一种允许模型在本地环境中执行 shell 命令的工具。 + 允许模型在本地环境中执行 shell 命令的工具。 - `type: "local_shell"` @@ -1821,7 +1821,7 @@ - `Shell object { type, allowed_callers, environment }` - 一种允许模型执行 shell 命令的工具。 + 允许模型执行 shell 命令的工具。 - `type: "shell"` @@ -1843,13 +1843,13 @@ - `type: "container_auto"` - 自动为此请求创建容器 + 自动为本次请求创建一个容器 - `"container_auto"` - `file_ids: optional array of string` - 可选的已上传文件列表，供你的代码使用。 + 可供代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -1873,13 +1873,13 @@ - `skills: optional array of SkillReference or InlineSkill` - 可选的技能列表，按 ID 或内联数据引用。 + 通过 id 引用或内联数据的可选技能列表。 - `SkillReference object { skill_id, type, version }` - `skill_id: string` - 所引用技能的 ID。 + 被引用技能的 ID。 - `type: "skill_reference"` @@ -1889,21 +1889,21 @@ - `version: optional string` - 可选的技能版本。使用正整数或 'latest'。省略时使用默认值。 + 可选的技能版本。使用正整数或 'latest'。省略则使用默认值。 - `InlineSkill object { description, name, source, type }` - `description: string` - 该技能的描述。 + 技能的描述。 - `name: string` - 该技能的名称。 + 技能的名称。 - `source: InlineSkillSource` - 内联技能负载 + 内联技能载荷 - `data: string` @@ -1911,19 +1911,19 @@ - `media_type: "application/zip"` - 内联技能负载的媒体类型。必须为 `application/zip`. + 内联技能载荷的媒体类型。必须为 `application/zip`. - `"application/zip"` - `type: "base64"` - 内联技能来源的类型。必须为 `base64`. + 内联技能源的类型。必须为 `base64`. - `"base64"` - `type: "inline"` - 为此请求定义内联技能。 + 为本次请求定义一个内联技能。 - `"inline"` @@ -1941,15 +1941,15 @@ - `description: string` - 该技能的描述。 + 技能的描述。 - `name: string` - 该技能的名称。 + 技能的名称。 - `path: string` - 包含该技能的目录的路径。 + 包含该技能的目录路径。 - `ContainerReference object { container_id, type }` @@ -1959,13 +1959,13 @@ - `type: "container_reference"` - 引用使用 /v1/containers 端点创建的容器 + 引用通过 /v1/containers 端点创建的容器 - `"container_reference"` - `Custom object { name, type, allowed_callers, 3 more }` - 一种使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -1987,7 +1987,7 @@ - `defer_loading: optional boolean` - 是否应延迟此工具并可通过工具搜索发现。 + 此工具是否应被延迟，并通过工具搜索发现。 - `description: optional string` @@ -2017,7 +2017,7 @@ - `syntax: "lark" or "regex"` - 语法定义的语法。其中之一为 `lark` 或 `regex`. + 语法定义的语法格式。之一为 `lark` 或 `regex`. - `"lark"` @@ -2031,15 +2031,15 @@ - `Namespace object { description, name, tools, type }` - 将函数/自定义工具分组到共享命名空间下。 + 在共享命名空间下对函数/自定义工具进行分组。 - `description: string` - 显示给模型的命名空间描述。 + 展示给模型的命名空间描述。 - `name: string` - 工具调用中使用的命名空间名称（例如， `crm`). + 用于工具调用中的命名空间名称（例如， `crm`). - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` @@ -2063,23 +2063,23 @@ - `defer_loading: optional boolean` - 是否应延迟此函数并可通过工具搜索发现。 + 此函数是否应被延迟，并通过工具搜索发现。 - `description: optional string or null` - `output_schema: optional map[unknown] or null` - 一个 JSON Schema，描述此函数工具的字符串输出中编码的 JSON 值。这不描述内容数组输出。 + 描述此函数工具中以字符串形式输出的 JSON 值所对应的 JSON Schema。该字段不描述 content 数组形式的输出。 - `parameters: optional unknown or null` - `strict: optional boolean or null` - 是否强制严格参数验证。如果省略，Responses 会在 schema 兼容时尝试使用严格验证，否则回退到非严格验证。 + 是否强制启用严格的参数校验。若省略，Responses 会在 schema 兼容时尝试使用严格校验，否则回退到非严格校验。 - `Custom object { name, type, allowed_callers, 3 more }` - 一种使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2101,7 +2101,7 @@ - `defer_loading: optional boolean` - 是否应延迟此工具并可通过工具搜索发现。 + 此工具是否应被延迟，并通过工具搜索发现。 - `description: optional string` @@ -2119,7 +2119,7 @@ - `ToolSearch object { type, description, execution, parameters }` - 托管工具或 BYOT 工具搜索配置，用于延迟工具。 + 用于延迟工具的托管或 BYOT 工具搜索配置。 - `type: "tool_search"` @@ -2129,11 +2129,11 @@ - `description: optional string or null` - 为客户端执行的工具搜索工具显示的描述。 + 向模型展示的、用于描述由客户端执行的工具搜索工具的说明。 - `execution: optional "server" or "client"` - 工具搜索是由服务端还是客户端执行。 + 工具搜索是由服务端执行还是由客户端执行。 - `"server"` @@ -2141,15 +2141,15 @@ - `parameters: optional unknown or null` - 客户端执行的工具搜索工具的参数 schema。 + 由客户端执行的工具搜索工具的参数 schema。 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - 此工具搜索网页以获取相关结果用于响应。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). + 此工具会在网页上搜索相关结果以用于回复中。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 网页搜索工具的类型。之一 `web_search_preview` 或 `web_search_preview_2025_03_11`. + 网页搜索工具的类型，取值之一 `web_search_preview` 或 `web_search_preview_2025_03_11`. - `"web_search_preview"` @@ -2163,7 +2163,7 @@ - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。之一 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间的高层级用量指导，取值之一 `low`, `medium`，或 `high`. `medium` 是默认值。 - `"low"` @@ -2173,33 +2173,33 @@ - `user_location: optional object { type, city, country, 2 more } or null` - 用户的位置。 + 用户所在的位置。 - `type: "approximate"` - 位置近似类型。始终 `approximate`. + 位置近似值的类型，始终为 `approximate`. - `"approximate"` - `city: optional string or null` - 用户城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两位 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) 用户的，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` - 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) 用户的，例如。 `America/Los_Angeles`. + 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) ，例如。 `America/Los_Angeles`. - `ApplyPatch object { type, allowed_callers }` - 允许助手使用统一 diff 创建、删除或更新文件。 + 允许助手使用统一差异（unified diff）创建、删除或更新文件。 - `type: "apply_patch"` @@ -2217,19 +2217,19 @@ - `type: "tool_search_output"` - 项的类型。始终为 `tool_search_output`. + 该项的类型。始终为 `tool_search_output`. - `"tool_search_output"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `AdditionalTools object { id, role, tools, type }` - `id: string` - 附加工具项的唯一 ID。 + 该附加工具条目的唯一 ID。 - `role: "unknown" or "user" or "assistant" or 5 more` @@ -2253,23 +2253,23 @@ - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - 在此项中提供的附加工具定义。 + 此条目中可用的附加工具定义。 - `Function object { name, parameters, strict, 5 more }` - 定义你代码中模型可选择调用的函数。了解有关 [函数调用](https://platform.openai.com/docs/guides/function-calling). + 在你自己代码中定义一个可由模型选择调用的函数。了解更多关于 [函数调用](https://platform.openai.com/docs/guides/function-calling). - `name: string` - 要调用的函数的名称。 + 要调用的函数名称。 - `parameters: map[unknown] or null` - 描述函数参数的 JSON schema 对象。 + 描述该函数参数的 JSON schema 对象。 - `strict: boolean or null` - 是否对此函数工具强制执行严格参数验证。 + 是否对该函数工具强制执行严格的参数校验。 - `type: "function"` @@ -2287,19 +2287,19 @@ - `defer_loading: optional boolean` - 此函数是否延迟并通过工具搜索加载。 + 该函数是否被延迟加载并通过工具搜索加载。 - `description: optional string or null` - 函数的描述。模型据此决定是否调用该函数。 + 对该函数的描述。供模型用来决定是否调用该函数。 - `output_schema: optional map[unknown] or null` - 一个 JSON schema 对象，描述此函数字符串输出中编码的 JSON 值。 + 用于描述该函数字符串输出中所编码 JSON 值的 JSON schema 对象。 - `FileSearch object { type, vector_store_ids, filters, 2 more }` - 一个从上传文件中搜索相关内容的工具。了解更多关于 [文件搜索 工具](https://platform.openai.com/docs/guides/tools-file-search). + 从已上传文件中搜索相关内容的一款工具。了解更多关于 [文件搜索 工具](https://platform.openai.com/docs/guides/tools-file-search). - `type: "file_search"` @@ -2309,43 +2309,43 @@ - `vector_store_ids: array of string` - 要搜索的向量存储的 ID。 + 要搜索的向量存储 ID。 - `filters: optional ComparisonFilter or CompoundFilter or null` - 要应用的过滤器。 + 要应用的筛选条件。 - `ComparisonFilter object { key, type, value }` - 用于通过定义的比较操作将指定属性键与给定值进行比较的过滤器。 + 用于将指定的属性键与给定值按定义的比较运算进行比较的筛选器。 - `CompoundFilter object { filters, type }` - 使用以下方式组合多个过滤器 `and` 或 `or`. + 使用以下方式组合多个筛选器 `and` 或 `or`. - `max_num_results: optional number` - 要返回的最大结果数。此数字应在 1 到 50 之间（含）。 + 返回的最大结果数量。该数值应介于 1 到 50 之间（含端点）。 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 搜索的排名选项。 + 搜索的排序选项。 - `hybrid_search: optional object { embedding_weight, text_weight }` - 当启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。 + 在启用混合搜索时，用于控制倒数排名融合在语义嵌入匹配与稀疏关键词匹配之间平衡的权重。 - `embedding_weight: number` - 倒数排名融合中嵌入的权重。 + 在倒数排名融合中嵌入向量的权重。 - `text_weight: number` - 倒数排名融合中文本的权重。 + 在倒数排名融合中文本的权重。 - `ranker: optional "auto" or "default-2024-11-15"` - 用于文件搜索的排名器。 + 用于文件搜索的排序器。 - `"auto"` @@ -2353,21 +2353,21 @@ - `score_threshold: optional number` - 文件搜索的分数阈值，一个介于 0 和 1 之间的数字。更接近 1 的数字将尝试仅返回最相关的结果，但可能返回较少的结果。 + 文件搜索的分数阈值，介于 0 到 1 之间的数值。越接近 1 的数值会尝试仅返回相关性最高的结果，但返回的结果数量可能更少。 - `Computer object { type }` - 一个控制虚拟计算机的工具。了解有关 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: "computer"` - 计算机工具的类型。始终为 `computer`. + computer tool 的类型，恒为 `computer`. - `"computer"` - `ComputerUsePreview object { display_height, display_width, environment, type }` - 一个控制虚拟计算机的工具。了解有关 [计算机工具](https://platform.openai.com/docs/guides/tools-computer-use). + 用于控制虚拟计算机的工具。详细了解 [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: number` @@ -2393,18 +2393,18 @@ - `type: "computer_use_preview"` - 计算机使用工具的类型。始终为 `computer_use_preview`. + computer use 工具的类型，恒为 `computer_use_preview`. - `"computer_use_preview"` - `WebSearch object { type, external_web_access, filters, 2 more }` - 搜索互联网以获取与提示相关的来源。详细了解 + 在互联网上搜索与提示相关的来源。详细了解 [网页搜索工具](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` - 网页搜索工具的类型。之一 `web_search` 或 `web_search_2025_08_26`. + 网页搜索工具的类型，取值之一 `web_search` 或 `web_search_2025_08_26`. - `"web_search"` @@ -2412,22 +2412,22 @@ - `external_web_access: optional boolean` - 允许网页搜索进行实时互联网访问。省略时默认为 true。当为 false 时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 + 允许 网页搜索访问实时互联网。省略时默认为 true。当为 false 时，网页搜索工具以离线/仅缓存模式运行，不会获取新的外部内容。 - `filters: optional object { allowed_domains } or null` - 搜索的过滤器。 + 搜索的筛选条件。 - `allowed_domains: optional array of string or null` - 允许搜索的域名。如果未提供，则允许所有域名。 - 所提供域名的子域名也允许。 + 搜索所允许的域名。如果未提供，则允许所有域名。 + 所提供域名的子域名也同样被允许。 示例： `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。之一 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间的高层级用量指导，取值之一 `low`, `medium`，或 `high`. `medium` 是默认值。 - `"low"` @@ -2441,38 +2441,38 @@ - `city: optional string or null` - 用户城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两位 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) 用户的，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` - 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) 用户的，例如。 `America/Los_Angeles`. + 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) ，例如。 `America/Los_Angeles`. - `type: optional "approximate"` - 位置近似类型。始终 `approximate`. + 位置近似值的类型，始终为 `approximate`. - `"approximate"` - `Mcp object { server_label, type, allowed_callers, 9 more }` - 通过远程模型上下文协议为模型提供额外工具 - （MCP）服务器。 [了解更多关于 MCP 的信息](/docs/guides/tools-remote-mcp). + 通过远程 Model Context Protocol 让模型能够访问其他工具 + (MCP) 服务器。 [详细了解 MCP](/docs/guides/tools-remote-mcp). - `server_label: string` - 此 MCP 服务器的标签，用于在工具调用中标识它。 + 此 MCP 服务器的标签，用于在工具调用中识别该服务器。 - `type: "mcp"` - MCP 工具的类型。始终 `mcp`. + MCP 工具的类型。始终为 `mcp`. - `"mcp"` @@ -2486,20 +2486,20 @@ - `allowed_tools: optional array of string or object { read_only, tool_names } or null` - 允许的工具名称列表或过滤器对象。 + 允许使用的工具名称列表或过滤对象。 - `McpAllowedTools = array of string` - 允许的工具名称的字符串数组 + 允许使用的工具名称组成的字符串数组 - `McpToolFilter object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2508,26 +2508,26 @@ - `authorization: optional string` - 一个 OAuth 访问令牌，可与远程 MCP 服务器一起使用， - 可与自定义 MCP 服务器 URL 或服务连接器一起使用。你的应用程序 + 可与远程 MCP 服务器一起使用的 OAuth 访问令牌，可用于 + 自定义 MCP 服务器 URL 或服务连接器。你的应用 必须处理 OAuth 授权流程并在此处提供令牌。 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - 服务连接器的标识符，如 ChatGPT 中可用的那些。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 其中之一。了解更多 - 关于服务连接器的信息 [此处](/docs/guides/tools-remote-mcp#connectors). + 服务连接器的标识符，例如 ChatGPT 中提供的连接器。其中之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。了解更多 + 关于服务连接器 [此处](/docs/guides/tools-remote-mcp#connectors). - 目前支持 `connector_id` 支持的值为： + 当前支持 `connector_id` 值包括： - - Dropbox： `connector_dropbox` - - Gmail： `connector_gmail` - - Google Calendar： `connector_googlecalendar` - - Google Drive： `connector_googledrive` - - Microsoft Teams： `connector_microsoftteams` - - Outlook Calendar： `connector_outlookcalendar` - - Outlook Email： `connector_outlookemail` - - SharePoint： `connector_sharepoint` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - `"connector_dropbox"` @@ -2547,31 +2547,31 @@ - `defer_loading: optional boolean` - 此 MCP 工具是否被延迟并通过工具搜索发现。 + 此 MCP 工具是否为延迟发现工具，需通过工具搜索获取。 - `headers: optional map[string] or null` - 要发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 + 发送到 MCP 服务器的可选 HTTP 标头。用于身份验证 或其他用途。 - `require_approval: optional object { always, never } or "always" or "never" or null` - 指定 MCP 服务器的哪些工具需要审批。 + 指定 MCP 服务器中哪些工具需要审批。 - `McpToolApprovalFilter object { always, never }` - 指定 MCP 服务器的哪些工具需要审批。可以是 - `always`, `never`，或与需要审批的工具关联的过滤器对象 + 指定 MCP 服务器中哪些工具需要审批。可以是 + `always`, `never`，也可以是与需要审批的工具关联的过滤器对象 。 - `always: optional object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2580,12 +2580,12 @@ - `never: optional object { read_only, tool_names }` - 指定允许哪些工具的过滤器对象。 + 用于指定允许使用哪些工具的过滤对象。 - `read_only: optional boolean` - 指示工具是否修改数据或为只读。如果 - MCP 服务器被 [注释为 `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + 指示工具是否修改数据或是否为只读。如果 MCP 服务器 + 被标记为 [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), 它将匹配此过滤器。 - `tool_names: optional array of string` @@ -2594,9 +2594,9 @@ - `McpToolApprovalSetting = "always" or "never"` - 为所有工具指定一个审批策略。可以是 `always` 或 + 为所有工具指定统一的审批策略。可选值为 `always` 或 `never`。之一。当设置为 `always`，时，所有工具都需要审批。当设置为 - 时 `never`，所有工具均无需审批。 + 时 `never`，所有工具都将无需审批。 - `"always"` @@ -2608,23 +2608,23 @@ - `server_url: optional string` - MCP 服务器的 URL。必须提供 `server_url`, `connector_id`，或 - `tunnel_id` 之一。 + MCP 服务器的 URL。以下其中之一 `server_url`, `connector_id`，或 + `tunnel_id` 必须提供。 - `tunnel_id: optional string` - 安全 MCP 隧道 ID，用于替代直接服务器 URL。必须提供 - `server_url`, `connector_id`，或 `tunnel_id` 之一。 + 用于替代直接服务器 URL 的 Secure MCP Tunnel ID。以下其中之一 + `server_url`, `connector_id`，或 `tunnel_id` 必须提供。 - `CodeInterpreter object { container, type, allowed_callers }` - 一个运行 Python 代码以帮助生成提示响应的工具。 + 用于运行 Python 代码以帮助生成针对提示的响应的工具。 - `container: string or object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器。可以是容器 ID 或一个 - 指定上传文件 ID 的对象，以使这些文件可供你的代码使用，并附带 - 可选 `memory_limit` 设置。 + 代码解释器容器。可以是容器 ID，或是指定了可供代码使用的已上传文件 ID 以及一个 + 可选 + 可选 `memory_limit` 设置的对象。 - `string` @@ -2632,7 +2632,7 @@ - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 代码解释器容器的配置。可选择指定要运行代码的文件的 ID。 + 代码解释器容器的配置。可选择指定要在其上运行代码的文件 ID。 - `type: "auto"` @@ -2642,7 +2642,7 @@ - `file_ids: optional array of string` - 可选的已上传文件列表，供你的代码使用。 + 可供代码使用的已上传文件的可选列表。 - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` @@ -2698,7 +2698,7 @@ - `action: optional "generate" or "edit" or "auto"` - 是生成新图像还是编辑现有图像。默认值： `auto`. + 是生成新图像还是编辑已有图像。默认值： `auto`. - `"generate"` @@ -2708,10 +2708,10 @@ - `background: optional "transparent" or "opaque" or "auto"` - 设置生成图像的背景。选项之一： `transparent`, - `opaque`，或 `auto`。透明背景可用于 + 设置生成图像的背景。可选值为 `transparent`, + `opaque`，或 `auto`。透明背景适用于 支持的 GPT 图像模型。对于 `gpt-image-2` 和 - `gpt-image-2-2026-04-21`，此支持处于预览阶段。使用 + `gpt-image-2-2026-04-21`，此支持为预览阶段。使用 `transparent`，时，将输出格式设置为 `png` 或 `webp`。默认值： `auto`. - `"transparent"` @@ -2722,7 +2722,7 @@ - `input_fidelity: optional "high" or "low" or null` - 控制模型在匹配输入图像的风格和特征（尤其是面部特征）方面投入多少努力。此参数仅支持 `gpt-image-1` 和 `gpt-image-1.5` 及更高版本的模型，不支持 `gpt-image-1-mini`。支持 `high` 和 `low`。默认值： `low`. + 控制模型在匹配输入图像的风格和特征（尤其是面部特征）时所投入的精力。此参数仅在 `gpt-image-1` 和 `gpt-image-1.5` 及更高版本模型中受支持，不支持 `gpt-image-1-mini`。支持 `high` 和 `low`。默认为 `low`. - `"high"` @@ -2730,20 +2730,20 @@ - `input_image_mask: optional object { file_id, image_url }` - 用于修复的可选蒙版。包含 `image_url` - （字符串，可选）和 `file_id` （字符串，可选）。 + 用于局部重绘的可选蒙版。包含 `image_url` + （字符串，可选）和 `file_id` (string, optional). - `file_id: optional string` - 掩码图像的文件 ID。 + 掩膜图像的文件 ID。 - `image_url: optional string` - Base64 编码的掩码图像。 + Base64 编码的掩膜图像。 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。之一为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -2752,7 +2752,7 @@ - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 2 more` - 要使用的图像生成模型。之一为 `gpt-image-1`, + 要使用的图像生成模型。可选值为 `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`，或 `chatgpt-image-latest`。默认值： `gpt-image-1`. @@ -2769,7 +2769,7 @@ - `moderation: optional "auto" or "low"` - 生成图像的审核级别。默认值： `auto`. + 生成图像的内容审核级别。默认值： `auto`. - `"auto"` @@ -2781,7 +2781,7 @@ - `output_format: optional "png" or "webp" or "jpeg"` - 生成图像的输出格式。之一为 `png`, `webp`，或 + 生成图像的输出格式。可选值为 `png`, `webp`，或 `jpeg`。默认值： `png`. - `"png"` @@ -2792,11 +2792,11 @@ - `partial_images: optional number` - 在流式模式下生成的部分图像数量，范围为 0（默认值）到 3。 + 在流式模式下生成的部分图像数量，取值范围为 0（默认值）到 3。 - `quality: optional "low" or "medium" or "high" or "auto"` - 生成图像的质量。之一为 `low`, `medium`, `high`, + 生成图像的质量。可选值为 `low`, `medium`, `high`, 或 `auto`。默认值： `auto`. - `"low"` @@ -2809,13 +2809,13 @@ - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`, 以及 `1024x1536` 受 GPT 图像模型支持； `auto` 适用于允许自动调整尺寸的模型。对于 `dall-e-2`，使用以下之一 `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持以 `WIDTHxHEIGHT` 字符串形式指定任意分辨率，例如 `1536x864`。宽度和高度都必须能被 16 整除，并且请求的长宽比必须介于 1:3 和 3:1 之间。超过 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，和 `1024x1536` 由 GPT image 模型支持； `auto` 由支持自动尺寸的模型支持。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。之一。对于 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. - `string` - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持任意分辨率，作为 `WIDTHxHEIGHT` 字符串，例如 `1536x864`。宽度和高度都必须能被 16 整除，且请求的宽高比必须在 1:3 到 3:1 之间。高于 `2560x1440` 的分辨率为实验性，支持的最大分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边缘限制。标准尺寸 `1024x1024`, `1536x1024`, 以及 `1024x1536` 受 GPT 图像模型支持； `auto` 适用于允许自动调整尺寸的模型。对于 `dall-e-2`，使用以下之一 `256x256`, `512x512`，或 `1024x1024`。对于 `dall-e-3`，使用以下之一 `1024x1024`, `1792x1024`，或 `1024x1792`. + 生成图像的尺寸。对于 `gpt-image-2` 和 `gpt-image-2-2026-04-21`，支持以 `WIDTHxHEIGHT` 字符串形式指定任意分辨率，例如 `1536x864`。宽度和高度都必须能被 16 整除，并且请求的长宽比必须介于 1:3 和 3:1 之间。超过 `2560x1440` 的分辨率为实验性，最大支持的分辨率为 `3840x2160`。请求的尺寸还必须满足模型当前的像素和边长限制。标准尺寸 `1024x1024`, `1536x1024`，和 `1024x1536` 由 GPT image 模型支持； `auto` 由支持自动尺寸的模型支持。对于 `dall-e-2`，请使用 `256x256`, `512x512`，或 `1024x1024`。之一。对于 `dall-e-3`，请使用 `1024x1024`, `1792x1024`，或 `1024x1792`. - `"1024x1024"` @@ -2827,7 +2827,7 @@ - `LocalShell object { type }` - 一种允许模型在本地环境中执行 shell 命令的工具。 + 允许模型在本地环境中执行 shell 命令的工具。 - `type: "local_shell"` @@ -2837,7 +2837,7 @@ - `Shell object { type, allowed_callers, environment }` - 一种允许模型执行 shell 命令的工具。 + 允许模型执行 shell 命令的工具。 - `type: "shell"` @@ -2863,7 +2863,7 @@ - `Custom object { name, type, allowed_callers, 3 more }` - 一种使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2885,7 +2885,7 @@ - `defer_loading: optional boolean` - 是否应延迟此工具并可通过工具搜索发现。 + 此工具是否应被延迟，并通过工具搜索发现。 - `description: optional string` @@ -2897,15 +2897,15 @@ - `Namespace object { description, name, tools, type }` - 将函数/自定义工具分组到共享命名空间下。 + 在共享命名空间下对函数/自定义工具进行分组。 - `description: string` - 显示给模型的命名空间描述。 + 展示给模型的命名空间描述。 - `name: string` - 工具调用中使用的命名空间名称（例如， `crm`). + 用于工具调用中的命名空间名称（例如， `crm`). - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` @@ -2929,23 +2929,23 @@ - `defer_loading: optional boolean` - 是否应延迟此函数并可通过工具搜索发现。 + 此函数是否应被延迟，并通过工具搜索发现。 - `description: optional string or null` - `output_schema: optional map[unknown] or null` - 一个 JSON Schema，描述此函数工具的字符串输出中编码的 JSON 值。这不描述内容数组输出。 + 描述此函数工具中以字符串形式输出的 JSON 值所对应的 JSON Schema。该字段不描述 content 数组形式的输出。 - `parameters: optional unknown or null` - `strict: optional boolean or null` - 是否强制严格参数验证。如果省略，Responses 会在 schema 兼容时尝试使用严格验证，否则回退到非严格验证。 + 是否强制启用严格的参数校验。若省略，Responses 会在 schema 兼容时尝试使用严格校验，否则回退到非严格校验。 - `Custom object { name, type, allowed_callers, 3 more }` - 一种使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) + 使用指定格式处理输入的自定义工具。了解更多关于 [自定义工具](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2967,7 +2967,7 @@ - `defer_loading: optional boolean` - 是否应延迟此工具并可通过工具搜索发现。 + 此工具是否应被延迟，并通过工具搜索发现。 - `description: optional string` @@ -2985,7 +2985,7 @@ - `ToolSearch object { type, description, execution, parameters }` - 托管工具或 BYOT 工具搜索配置，用于延迟工具。 + 用于延迟工具的托管或 BYOT 工具搜索配置。 - `type: "tool_search"` @@ -2995,11 +2995,11 @@ - `description: optional string or null` - 为客户端执行的工具搜索工具显示的描述。 + 向模型展示的、用于描述由客户端执行的工具搜索工具的说明。 - `execution: optional "server" or "client"` - 工具搜索是由服务端还是客户端执行。 + 工具搜索是由服务端执行还是由客户端执行。 - `"server"` @@ -3007,15 +3007,15 @@ - `parameters: optional unknown or null` - 客户端执行的工具搜索工具的参数 schema。 + 由客户端执行的工具搜索工具的参数 schema。 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - 此工具搜索网页以获取相关结果用于响应。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). + 此工具会在网页上搜索相关结果以用于回复中。了解更多关于 [网页搜索工具](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 网页搜索工具的类型。之一 `web_search_preview` 或 `web_search_preview_2025_03_11`. + 网页搜索工具的类型，取值之一 `web_search_preview` 或 `web_search_preview_2025_03_11`. - `"web_search_preview"` @@ -3029,7 +3029,7 @@ - `search_context_size: optional "low" or "medium" or "high"` - 用于搜索的上下文窗口空间量的高级指导。之一 `low`, `medium`，或 `high`. `medium` 是默认值。 + 用于搜索的上下文窗口空间的高层级用量指导，取值之一 `low`, `medium`，或 `high`. `medium` 是默认值。 - `"low"` @@ -3039,33 +3039,33 @@ - `user_location: optional object { type, city, country, 2 more } or null` - 用户的位置。 + 用户所在的位置。 - `type: "approximate"` - 位置近似类型。始终 `approximate`. + 位置近似值的类型，始终为 `approximate`. - `"approximate"` - `city: optional string or null` - 用户城市的自由文本输入，例如 `San Francisco`. + 用户所在城市的自由文本输入，例如 `San Francisco`. - `country: optional string or null` - 两位 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) 用户的，例如。 `US`. + 两位字母的 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1) ，例如。 `US`. - `region: optional string or null` - 用户地区的自由文本输入，例如 `California`. + 用户所在地区的自由文本输入，例如 `California`. - `timezone: optional string or null` - 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) 用户的，例如。 `America/Los_Angeles`. + 该 [IANA 时区](https://timeapi.io/documentation/iana-timezones) ，例如。 `America/Los_Angeles`. - `ApplyPatch object { type, allowed_callers }` - 允许助手使用统一 diff 创建、删除或更新文件。 + 允许助手使用统一差异（unified diff）创建、删除或更新文件。 - `type: "apply_patch"` @@ -3083,15 +3083,15 @@ - `type: "additional_tools"` - 项的类型。始终为 `additional_tools`. + 该项的类型。始终为 `additional_tools`. - `"additional_tools"` - `Reasoning object { id, summary, type, 3 more }` - 推理模型生成时使用的思维链的描述 - 响应。请确保在手动管理上下文时将这些项目包含在 `input` Responses API - 用于对话的后续轮次，如果你手动 + 对推理模型在生成回复过程中所使用的思维链的描述 + 。如果在手动管理上下文，请务必在后续对话轮次中将这些条目包含在你发送至 `input` Responses API 的请求中 + ，以便保留推理内容 [管理上下文](/docs/guides/conversation-state). - `id: string` @@ -3104,17 +3104,17 @@ - `text: string` - 模型迄今为止的推理输出的摘要。 + 对模型迄今为止推理输出的摘要。 - `type: "summary_text"` - 对象类型。始终为 `summary_text`. + 对象的类型。始终为 `summary_text`. - `"summary_text"` - `type: "reasoning"` - 对象类型。始终为 `reasoning`. + 对象的类型。始终为 `reasoning`. - `"reasoning"` @@ -3124,7 +3124,7 @@ - `text: string` - 来自模型的推理文本。 + 模型返回的推理文本。 - `type: "reasoning_text"` @@ -3134,20 +3134,20 @@ - `encrypted_content: optional string or null` - 推理项目的加密内容。默认情况下，此字段由以下请求填充 - 对于由以下请求返回的推理项目， `POST /v1/responses` 和 WebSocket - `response.create` 请求。 + 推理项的加密内容。默认情况下会填充此字段 + 针对通过 `POST /v1/responses` 和 WebSocket + `response.create` 请求返回的推理项。 - 当进行流式传输时，请使用完整的推理项目及其 - `encrypted_content` 来自 `response.output_item.done` 事件，在 - 后续请求中。 `encrypted_content` 中的 - `response.output_item.added` 可能不完整。这一点尤其重要 - 当 `store` 为 `false` 或使用零数据保留时。 + 流式传输时，请在后续请求中使用已完成的推理项及其 + `encrypted_content` 来自 `response.output_item.done` 事件。 + 后续请求中的 `encrypted_content` 可能 + `response.output_item.added` 不完整。这一点在 + 时尤其重要 `store` 为 `false` 或使用零数据保留时。 - `status: optional "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -3159,23 +3159,23 @@ - `id: string` - 程序项目的唯一 ID。 + 程序项的唯一 ID。 - `call_id: string` - 程序项目的稳定调用 ID。 + 程序项的稳定调用 ID。 - `code: string` - 由编程工具调用执行的 JavaScript 源代码。 + 由程序化工具调用执行的 JavaScript 源码。 - `fingerprint: string` - Opaque program replay fingerprint that must be round-tripped. + 必须往返传输的不透明程序重放指纹。 - `type: "program"` - 项的类型。始终为 `program`. + 该项的类型。始终为 `program`. - `"program"` @@ -3183,19 +3183,19 @@ - `id: string` - The unique ID of the program output item. + 程序输出项的唯一 ID。 - `call_id: string` - The call ID of the program item. + 程序项的调用 ID。 - `result: string` - The result produced by the program item. + 程序项生成的结果。 - `status: "completed" or "incomplete"` - The terminal status of the program output item. + 程序输出项的最终状态。 - `"completed"` @@ -3203,47 +3203,47 @@ - `type: "program_output"` - 项的类型。始终为 `program_output`. + 该项的类型。始终为 `program_output`. - `"program_output"` - `Compaction object { id, encrypted_content, type, created_by }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + 由API生成的压缩项 [`v1/responses/compact` 接口](/docs/api-reference/responses/compact). - `id: string` - The unique ID of the compaction item. + 压缩项的唯一 ID。 - `encrypted_content: string` - The encrypted content that was produced by compaction. + 压缩生成的内容（已加密）。 - `type: "compaction"` - 项的类型。始终为 `compaction`. + 该项的类型。始终为 `compaction`. - `"compaction"` - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `ImageGenerationCall object { id, result, status, type }` - An image generation request made by the model. + 模型发起的图像生成请求。 - `id: string` - The unique ID of the image generation call. + 图像生成调用的唯一 ID。 - `result: string or null` - The generated image encoded in base64. + 以 base64 编码的生成图像。 - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the image generation call. + 图像生成调用的状态。 - `"in_progress"` @@ -3255,62 +3255,62 @@ - `type: "image_generation_call"` - The type of the image generation call. Always `image_generation_call`. + 图像生成调用的类型。始终为 `image_generation_call`. - `"image_generation_call"` - `CodeInterpreterCall object { id, code, container_id, 3 more }` - A tool call to run code. + 运行代码的工具调用。 - `id: string` - The unique ID of the code interpreter tool call. + 代码解释器工具调用的唯一 ID。 - `code: string or null` - The code to run, or null if not available. + 要运行的代码，若不可用则为 null。 - `container_id: string` - The ID of the container used to run the code. + 用于运行代码的容器 ID。 - `outputs: array of object { logs, type } or object { type, url } or null` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + 代码解释器生成的输出，例如日志或图像。 + 若无任何输出可为 null。 - `Logs object { logs, type }` - 代码解释器输出的日志。 + 来自代码解释器的日志输出。 - `logs: string` - 代码解释器输出的日志。 + 来自代码解释器的日志输出。 - `type: "logs"` - 输出的类型。始终为 `logs`. + 输出类型。始终为 `logs`. - `"logs"` - `Image object { type, url }` - 代码解释器输出的图像。 + 来自代码解释器的图片输出。 - `type: "image"` - 输出的类型。始终为 `image`. + 输出类型。始终为 `image`. - `"image"` - `url: string` - 代码解释器输出图像的 URL。 + 来自代码解释器的图片输出的 URL。 - `status: "in_progress" or "completed" or "incomplete" or 2 more` - 代码解释器工具调用的状态。有效值为 `in_progress`, `completed`, `incomplete`, `interpreting`, 以及 `failed`. + 代码解释器工具调用的状态。有效值为 `in_progress`, `completed`, `incomplete`, `interpreting`，和 `failed`. - `"in_progress"` @@ -3338,7 +3338,7 @@ - `action: object { command, env, type, 3 more }` - 在服务器上执行 shell 命令。 + 在服务端执行 shell 命令。 - `command: array of string` @@ -3360,7 +3360,7 @@ - `user: optional string or null` - 运行命令的可选用户。 + 运行命令时所使用的可选用户。 - `working_directory: optional string or null` @@ -3368,7 +3368,7 @@ - `call_id: string` - 模型生成的本地 shell 工具调用的唯一 ID。 + 由模型生成的本地 shell 工具调用的唯一 ID。 - `status: "in_progress" or "completed" or "incomplete"` @@ -3392,7 +3392,7 @@ - `id: string` - 模型生成的本地 shell 工具调用的唯一 ID。 + 由模型生成的本地 shell 工具调用的唯一 ID。 - `output: string` @@ -3400,13 +3400,13 @@ - `type: "local_shell_call_output"` - 本地 shell 工具调用输出的类型。始终 `local_shell_call_output`. + 本地 shell 工具调用输出的类型。始终为 `local_shell_call_output`. - `"local_shell_call_output"` - `status: optional "in_progress" or "completed" or "incomplete" or null` - 项目的状态。以下之一： `in_progress`, `completed`，或 `incomplete`. + 条目的状态，取值为 `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3416,29 +3416,29 @@ - `ShellCall object { id, action, call_id, 5 more }` - 在托管环境中执行一条或多条 shell 命令的工具调用。 + 在托管环境中执行一个或多个 shell 命令的工具调用。 - `id: string` - shell 工具调用的唯一 ID。当此项目通过 API 返回时填充。 + shell 工具调用的唯一 ID。当此条目通过 API 返回时填充。 - `action: object { commands, max_output_length, timeout_ms }` - 描述如何运行工具调用的 shell 命令和限制。 + 描述如何运行该工具调用的 shell 命令与限制。 - `commands: array of string` - `max_output_length: number or null` - 每条命令返回的最大字符数（可选）。 + 每个命令返回内容的可选最大字符数。 - `timeout_ms: number or null` - 命令的超时时间（毫秒，可选）。 + 命令的可选超时时间（毫秒）。 - `call_id: string` - 由模型生成的 shell 工具调用的唯一 ID。 + 模型生成的 shell 工具调用的唯一 ID。 - `environment: ResponseLocalEnvironment or ResponseContainerReference or null` @@ -3450,25 +3450,25 @@ - `type: "local"` - 环境类型。始终 `local`. + 环境类型。始终为 `local`. - `"local"` - `ResponseContainerReference object { container_id, type }` - 表示通过 /v1/containers 创建的容器。 + 表示使用 /v1/containers 创建的容器。 - `container_id: string` - `type: "container_reference"` - 环境类型。始终 `container_reference`. + 环境类型。始终为 `container_reference`. - `"container_reference"` - `status: "in_progress" or "completed" or "incomplete"` - shell 调用的状态。以下几种之一： `in_progress`, `completed`，或 `incomplete`. + shell 调用的状态。取值为 `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3478,13 +3478,13 @@ - `type: "shell_call"` - 项的类型。始终为 `shell_call`. + 该项的类型。始终为 `shell_call`. - `"shell_call"` - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -3496,7 +3496,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -3504,7 +3504,7 @@ - `created_by: optional string` - 创建此工具调用的实体的 ID。 + 创建此工具调用的实体 ID。 - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` @@ -3512,37 +3512,37 @@ - `id: string` - shell 调用输出的唯一 ID。当此项目通过 API 返回时填充。 + shell 调用输出的唯一 ID。当此条目通过 API 返回时填充。 - `call_id: string` - 由模型生成的 shell 工具调用的唯一 ID。 + 模型生成的 shell 工具调用的唯一 ID。 - `max_output_length: number or null` - shell 命令输出的最大长度。这是由模型生成的，应与原始输出一起传回。 + shell 命令输出的最大长度。这由模型生成，并应随原始输出一起传回。 - `output: array of object { outcome, stderr, stdout, created_by }` - shell 调用输出内容数组 + shell 调用输出内容的数组 - `outcome: object { type } or object { exit_code, type }` - 表示 shell 调用输出块的退出结果（带退出码）或超时结果。 + 表示 shell 调用输出块的退出结果（带有退出码）或超时结果。 - `Timeout object { type }` - 表示 shell 调用超过了其配置的时间限制。 + 表示 shell 调用超出了其配置的时间限制。 - `type: "timeout"` - 结果类型。始终 `timeout`. + 结果类型。始终为 `timeout`. - `"timeout"` - `Exit object { exit_code, type }` - 表示 shell 命令已完成并返回退出码。 + 表示 shell 命令已结束并返回了退出码。 - `exit_code: number` @@ -3550,25 +3550,25 @@ - `type: "exit"` - 结果类型。始终 `exit`. + 结果类型。始终为 `exit`. - `"exit"` - `stderr: string` - 捕获的标准错误输出。 + 捕获到的标准错误输出。 - `stdout: string` - 捕获的标准输出。 + 捕获到的标准输出。 - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `status: "in_progress" or "completed" or "incomplete"` - shell 调用输出的状态。取值之一： `in_progress`, `completed`，或 `incomplete`. + shell 调用输出的状态。取值之一为 `in_progress`, `completed`，或 `incomplete`. - `"in_progress"` @@ -3584,7 +3584,7 @@ - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -3596,7 +3596,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -3604,7 +3604,7 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `ApplyPatchCall object { id, call_id, operation, 4 more }` @@ -3612,7 +3612,7 @@ - `id: string` - apply patch 工具调用的唯一 ID。当此项目通过 API 返回时填充。 + apply patch 工具调用的唯一 ID。当此项通过 API 返回时填充。 - `call_id: string` @@ -3674,7 +3674,7 @@ - `status: "in_progress" or "completed"` - apply patch 工具调用的状态。取值之一： `in_progress` 或 `completed`. + apply patch 工具调用的状态。取值之一为 `in_progress` 或 `completed`. - `"in_progress"` @@ -3682,13 +3682,13 @@ - `type: "apply_patch_call"` - 项的类型。始终为 `apply_patch_call`. + 该项的类型。始终为 `apply_patch_call`. - `"apply_patch_call"` - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -3700,7 +3700,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -3708,15 +3708,15 @@ - `created_by: optional string` - 创建此工具调用的实体的 ID。 + 创建此工具调用的实体 ID。 - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - apply patch 工具调用所输出的内容。 + apply patch 工具调用输出的内容。 - `id: string` - apply patch 工具调用输出的唯一 ID。当此项目通过 API 返回时填充此字段。 + apply patch 工具调用输出的唯一 ID。当通过 API 返回此 item 时填充。 - `call_id: string` @@ -3732,13 +3732,13 @@ - `type: "apply_patch_call_output"` - 项的类型。始终为 `apply_patch_call_output`. + 该项的类型。始终为 `apply_patch_call_output`. - `"apply_patch_call_output"` - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -3750,7 +3750,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -3766,11 +3766,11 @@ - `McpListTools object { id, server_label, tools, 2 more }` - MCP 服务器上可用工具的列表。 + MCP 服务器上可用的工具列表。 - `id: string` - 列表的唯一 ID。 + 该列表的唯一 ID。 - `server_label: string` @@ -3782,7 +3782,7 @@ - `input_schema: unknown` - 描述工具输入的 JSON schema。 + 描述该工具输入的 JSON schema。 - `name: string` @@ -3790,7 +3790,7 @@ - `annotations: optional unknown or null` - 关于工具的附加注释。 + 关于该工具的其他注释。 - `description: optional string or null` @@ -3798,17 +3798,17 @@ - `type: "mcp_list_tools"` - 项的类型。始终为 `mcp_list_tools`. + 该项的类型。始终为 `mcp_list_tools`. - `"mcp_list_tools"` - `error: optional string or null` - 如果服务器无法列出工具，则显示错误消息。 + 如果服务器无法列出工具，则返回错误消息。 - `McpApprovalRequest object { id, arguments, name, 2 more }` - 请求人工批准工具调用的请求。 + 对工具调用的人工审批请求。 - `id: string` @@ -3824,11 +3824,11 @@ - `server_label: string` - 发出请求的 MCP 服务器的标签。 + 发起请求的 MCP 服务器的标签。 - `type: "mcp_approval_request"` - 项的类型。始终为 `mcp_approval_request`. + 该项的类型。始终为 `mcp_approval_request`. - `"mcp_approval_request"` @@ -3838,29 +3838,29 @@ - `id: string` - 审批响应的唯一 ID + 批准响应的唯一 ID - `approval_request_id: string` - 正在回答的审批请求的 ID。 + 被回复的批准请求的 ID。 - `approve: boolean` - 请求是否已获批准。 + 请求是否已批准。 - `type: "mcp_approval_response"` - 项的类型。始终为 `mcp_approval_response`. + 该项的类型。始终为 `mcp_approval_response`. - `"mcp_approval_response"` - `reason: optional string or null` - 决策的可选原因。 + 可选的决策原因。 - `McpCall object { id, arguments, name, 6 more }` - 在 MCP 服务器上调用工具。 + 对 MCP 服务器上某个工具的调用。 - `id: string` @@ -3868,11 +3868,11 @@ - `arguments: string` - 传递给工具的参数的 JSON 字符串。 + 传递给该工具的参数的 JSON 字符串。 - `name: string` - 所运行工具的名称。 + 已运行工具的名称。 - `server_label: string` @@ -3880,18 +3880,18 @@ - `type: "mcp_call"` - 项的类型。始终为 `mcp_call`. + 该项的类型。始终为 `mcp_call`. - `"mcp_call"` - `approval_request_id: optional string or null` - MCP 工具调用审批请求的唯一标识符。 - 在后续 `mcp_approval_response` 输入中包含此值以批准或拒绝相应的工具调用。 + MCP 工具调用批准请求的唯一标识符。 + 在后续的 `mcp_approval_response` 输入中包含此值，以批准或拒绝相应的工具调用。 - `error: optional McpToolCallError or null` - 工具调用产生的错误（如有）。 + 工具调用的错误（如果有）。 - `McpProtocolError object { code, message, type }` @@ -3927,7 +3927,7 @@ - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - 工具调用的状态。以下之一： `in_progress`, `completed`, `incomplete`, `calling`，或 `failed`. + 工具调用的状态。其值之一为 `in_progress`, `completed`, `incomplete`, `calling`，或 `failed`. - `"in_progress"` @@ -3943,7 +3943,7 @@ - `id: string` - 自定义工具调用项目的唯一 ID。 + 自定义工具调用项的唯一 ID。 - `call_id: string` @@ -3955,12 +3955,12 @@ - `name: string` - 正在调用的自定义工具的名称。 + 被调用的自定义工具的名称。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -3976,7 +3976,7 @@ - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -3988,7 +3988,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -3996,11 +3996,11 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `namespace: optional string` - 正在调用的自定义工具所在的命名空间。 + 被调用的自定义工具的命名空间。 - `CustomToolCallOutput object { id, call_id, output, 4 more }` @@ -4010,11 +4010,11 @@ - `call_id: string` - 调用 ID，用于将此自定义工具调用输出映射到自定义工具调用。 + 调用 ID，用于将此自定义工具调用输出映射到对应的自定义工具调用。 - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 你的代码生成的自定义工具调用的输出。 + 由你的代码生成的自定义工具调用输出。 可以是字符串或输出内容的列表。 - `StringOutput = string` @@ -4023,24 +4023,24 @@ - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - 自定义工具调用的文本、图像或文件输出。 + 自定义工具调用的文本、图片或文件输出。 - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 模型的文本输入。 + 发送给模型的文本输入。 - `ResponseInputImage object { detail, type, file_id, 2 more }` - 模型的图像输入。了解 [图像输入](/docs/guides/vision). + 发送给模型的图像输入。了解 [图像输入](/docs/guides/vision). - `ResponseInputFile object { type, detail, file_data, 4 more }` - 模型的文件输入。 + 发送给模型的输入文件。 - `status: "in_progress" or "completed" or "incomplete"` - 项目的状态。以下之一： `in_progress`, `completed`，或 - `incomplete`。通过 API 返回项目时填充。 + 条目的状态，取值为 `in_progress`, `completed`，或 + `incomplete`。当项通过 API 返回时填充。 - `"in_progress"` @@ -4050,13 +4050,13 @@ - `type: "custom_tool_call_output"` - 自定义工具调用输出的类型。始终 `custom_tool_call_output`. + 自定义工具调用输出的类型。始终为 `custom_tool_call_output`. - `"custom_tool_call_output"` - `caller: optional object { type } or object { caller_id, type } or null` - 产生此工具调用的执行上下文。 + 生成此工具调用的执行上下文。 - `Direct object { type }` @@ -4070,7 +4070,7 @@ - `caller_id: string` - 产生此工具调用的程序项的调用 ID。 + 生成此工具调用的程序项调用 ID。 - `type: "program"` @@ -4080,7 +4080,7 @@ - `created_by: optional string` - 创建该项的执行者标识符。 + 创建该条目的角色的标识符。 - `first_id: string` @@ -4088,7 +4088,7 @@ - `has_more: boolean` - 是否还有更多可用的项。 + 是否有更多可用项。 - `last_id: string` @@ -4096,7 +4096,7 @@ - `object: "list"` - 返回的对象类型，必须为 `list`. + 返回对象的类型，必须为 `list`. - `"list"` diff --git a/docs/zh/api/reference/resources/vector_stores.md b/docs/zh/api/reference/resources/vector_stores.md index 36cecd5..c36c345 100644 --- a/docs/zh/api/reference/resources/vector_stores.md +++ b/docs/zh/api/reference/resources/vector_stores.md @@ -1,22 +1,22 @@ # Vector Stores -> 如需查看完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 来获取。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt). 文档页面的 Markdown 版本可通过在页面 URL 后附加 `.md` 来获取。 ## 创建向量存储 **post** `/vector_stores` -创建一个向量存储。 +创建向量存储。 ### 请求体参数 - `chunking_strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam` - 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。仅当 `file_ids` 非空时适用。 + 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。仅当 `file_ids` 不为空时适用。 - `AutoFileChunkingStrategyParam object { type }` - 默认策略。此策略目前使用 `max_chunk_size_tokens` 和 `800` 。 `chunk_overlap_tokens` 和 `400`. + 默认策略。该策略当前使用 `max_chunk_size_tokens` 为 `800` 和 `chunk_overlap_tokens` 为 `400`. - `type: "auto"` @@ -32,13 +32,13 @@ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -56,26 +56,26 @@ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `file_ids: optional array of string` - 向量存储应使用的 [文件](/docs/api-reference/files) ID 列表。对诸如 `file_search` 可访问文件的。 + 一个 [File](/docs/api-reference/files) 的 ID 列表，向量存储应使用这些 ID。可用于诸如 `file_search` 可以访问文件。 - `metadata: optional Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: optional string` @@ -85,7 +85,7 @@ - `VectorStore object { id, created_at, file_counts, 8 more }` - 向量存储是已处理文件的集合，可被 `file_search` 工具使用。 + 向量存储是已处理文件的集合，可供 `file_search` 工具使用。 - `id: string` @@ -93,42 +93,42 @@ - `created_at: number` - 创建向量存储时的 Unix 时间戳（秒）。 + 向量存储创建时的 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` - `cancelled: number` - 已取消的文件数。 + 已取消的文件数量。 - `completed: number` - 已成功处理的文件数。 + 已成功处理的文件的数量。 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `last_active_at: number or null` - 向量存储上次活跃时的 Unix 时间戳（秒）。 + 向量存储最后活跃时的 Unix 时间戳（以秒为单位）。 - `metadata: Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: string` @@ -142,7 +142,7 @@ - `status: "expired" or "in_progress" or "completed"` - 向量存储的状态，可以是 `expired`, `in_progress`，或 `completed`。状态为 `completed` 表示向量存储已准备好使用。 + 向量存储的状态，可以是 `expired`, `in_progress`，或者 `completed`。状态为 `completed` 表示向量存储已准备好使用。 - `"expired"` @@ -160,17 +160,17 @@ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `expires_at: optional number or null` - 向量存储过期时的 Unix 时间戳（秒）。 + 向量存储过期时的 Unix 时间戳（以秒为单位）。 ### 示例 @@ -182,7 +182,7 @@ curl https://api.openai.com/v1/vector_stores \ -d '{}' ``` -#### 响应 +#### Response ```json { @@ -223,7 +223,7 @@ curl https://api.openai.com/v1/vector_stores \ }' ``` -#### 响应 +#### Response ```json { @@ -245,7 +245,7 @@ curl https://api.openai.com/v1/vector_stores \ ## 删除向量存储 -**删除** `/vector_stores/{vector_store_id}` +**delete** `/vector_stores/{vector_store_id}` 删除一个向量存储。 @@ -274,7 +274,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -294,7 +294,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ -X DELETE ``` -#### 响应 +#### Response ```json { @@ -314,19 +314,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo，以获取列表的下一页。 + 用于分页游标的对象 ID。 `after` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么后续调用可以包含 after=obj_foo，以便获取列表的下一页。 - `before: optional string` - 用于分页的游标。 `before` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 开头，那么你的后续调用可以包含 before=obj_foo，以获取列表的上一页。 + 用于分页游标的对象 ID。 `before` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 开头，那么后续调用可以包含 before=obj_foo，以便获取列表的上一页。 - `limit: optional number` - 对返回对象数量的限制。限制范围在 1 到 100 之间，默认为 20。 + 要返回的对象数量的上限。Limit 取值范围在 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` - 按对象的 `created_at` 时间戳排序。 `asc` 用于升序， `desc` 用于降序。 + 按对象的 `created_at` 时间戳排序。 `asc` 表示升序， `desc` 表示降序。 - `"asc"` @@ -342,42 +342,42 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `created_at: number` - 创建向量存储时的 Unix 时间戳（秒）。 + 向量存储创建时的 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` - `cancelled: number` - 已取消的文件数。 + 已取消的文件数量。 - `completed: number` - 已成功处理的文件数。 + 已成功处理的文件的数量。 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `last_active_at: number or null` - 向量存储上次活跃时的 Unix 时间戳（秒）。 + 向量存储最后活跃时的 Unix 时间戳（以秒为单位）。 - `metadata: Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: string` @@ -391,7 +391,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `status: "expired" or "in_progress" or "completed"` - 向量存储的状态，可以是 `expired`, `in_progress`，或 `completed`。状态为 `completed` 表示向量存储已准备好使用。 + 向量存储的状态，可以是 `expired`, `in_progress`，或者 `completed`。状态为 `completed` 表示向量存储已准备好使用。 - `"expired"` @@ -409,17 +409,17 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `expires_at: optional number or null` - 向量存储过期时的 Unix 时间戳（秒）。 + 向量存储过期时的 Unix 时间戳（以秒为单位）。 - `first_id: string` @@ -437,7 +437,7 @@ curl https://api.openai.com/v1/vector_stores \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -483,7 +483,7 @@ curl https://api.openai.com/v1/vector_stores \ -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -530,7 +530,7 @@ curl https://api.openai.com/v1/vector_stores \ **get** `/vector_stores/{vector_store_id}` -检索一个向量存储。 +检索向量存储。 ### 路径参数 @@ -540,7 +540,7 @@ curl https://api.openai.com/v1/vector_stores \ - `VectorStore object { id, created_at, file_counts, 8 more }` - 向量存储是已处理文件的集合，可被 `file_search` 工具使用。 + 向量存储是已处理文件的集合，可供 `file_search` 工具使用。 - `id: string` @@ -548,42 +548,42 @@ curl https://api.openai.com/v1/vector_stores \ - `created_at: number` - 创建向量存储时的 Unix 时间戳（秒）。 + 向量存储创建时的 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` - `cancelled: number` - 已取消的文件数。 + 已取消的文件数量。 - `completed: number` - 已成功处理的文件数。 + 已成功处理的文件的数量。 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `last_active_at: number or null` - 向量存储上次活跃时的 Unix 时间戳（秒）。 + 向量存储最后活跃时的 Unix 时间戳（以秒为单位）。 - `metadata: Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: string` @@ -597,7 +597,7 @@ curl https://api.openai.com/v1/vector_stores \ - `status: "expired" or "in_progress" or "completed"` - 向量存储的状态，可以是 `expired`, `in_progress`，或 `completed`。状态为 `completed` 表示向量存储已准备好使用。 + 向量存储的状态，可以是 `expired`, `in_progress`，或者 `completed`。状态为 `completed` 表示向量存储已准备好使用。 - `"expired"` @@ -615,17 +615,17 @@ curl https://api.openai.com/v1/vector_stores \ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `expires_at: optional number or null` - 向量存储过期时的 Unix 时间戳（秒）。 + 向量存储过期时的 Unix 时间戳（以秒为单位）。 ### 示例 @@ -635,7 +635,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -673,7 +673,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -687,7 +687,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ **post** `/vector_stores/{vector_store_id}/search` -根据查询和文件属性过滤器在向量存储中搜索相关分块。 +根据查询和文件属性筛选器，在向量存储中搜索相关分块。 ### 路径参数 @@ -697,7 +697,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `query: string or array of string` - 用于搜索的查询字符串 + 搜索的查询字符串 - `string` @@ -705,11 +705,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `filters: optional ComparisonFilter or CompoundFilter` - 基于文件属性应用的过滤器。 + 基于文件属性进行过滤的筛选条件。 - `ComparisonFilter object { key, type, value }` - 使用定义的比较操作，将指定属性键与给定值进行比较的过滤器。 + 用于将指定的属性键与给定值按定义的比较操作进行比较的筛选条件。 - `key: string` @@ -717,16 +717,16 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `type: "eq" or "ne" or "gt" or 5 more` - 指定比较操作符： `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 指定比较运算符： `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: 等于 - `ne`: 不等于 - `gt`: 大于 - - `gte`: 大于或等于 + - `gte`: 大于等于 - `lt`: 小于 - - `lte`: 小于或等于 - - `in`: 包含于 - - `nin`: 不包含于 + - `lte`: 小于等于 + - `in`: 属于 + - `nin`: 不属于 - `"eq"` @@ -746,7 +746,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `value: string or number or boolean or array of string or number` - 用于与属性键比较的值；支持字符串、数字或布尔类型。 + 用于与属性键进行比较的值；支持字符串、数字或布尔类型。 - `string` @@ -762,15 +762,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `CompoundFilter object { filters, type }` - 使用以下方式组合多个过滤器 `and` 或 `or`. + 使用以下方式组合多个筛选条件 `and` 或 `or`. - `filters: array of ComparisonFilter or unknown` - 要组合的过滤器数组。项目可以是 `ComparisonFilter` 或 `CompoundFilter`. + 要组合的筛选条件数组。各项可以是 `ComparisonFilter` 或 `CompoundFilter`. - `ComparisonFilter object { key, type, value }` - 使用定义的比较操作，将指定属性键与给定值进行比较的过滤器。 + 用于将指定的属性键与给定值按定义的比较操作进行比较的筛选条件。 - `unknown` @@ -784,15 +784,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `max_num_results: optional number` - 要返回的最大结果数。此数字应在 1 到 50 之间（含）。 + 返回结果的最大数量。该数值应介于 1 到 50（含）之间。 - `ranking_options: optional object { ranker, score_threshold }` - 搜索的排名选项。 + 搜索的排序选项。 - `ranker: optional "none" or "auto" or "default-2024-11-15"` - 启用重新排序；设置为 `none` 以禁用，这有助于减少延迟。 + 启用重排序；设置为 `none` 可关闭，这有助于降低延迟。 - `"none"` @@ -804,7 +804,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `rewrite_query: optional boolean` - 是否重写自然语言查询以进行向量搜索。 + 是否改写用于向量搜索的自然语言查询。 ### 返回 @@ -814,11 +814,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `attributes: map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -828,11 +828,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `content: array of object { text, type }` - 来自文件的内容块。 + 来自文件的内容分块。 - `text: string` - 从搜索中返回的文本内容。 + 从搜索返回的文本内容。 - `type: "text"` @@ -850,15 +850,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `score: number` - 结果的相似性得分。 + 该结果的相似度评分。 - `has_more: boolean` - 指示是否还有更多结果可获取。 + 指示是否还有更多结果可供获取。 - `next_page: string or null` - 下一页的令牌（如有）。 + 下一页的令牌（若有）。 - `object: "vector_store.search_results.page"` @@ -880,7 +880,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/search \ }' ``` -#### 响应 +#### Response ```json { @@ -919,7 +919,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ -d '{"query": "What is the return policy?", "filters": {...}}' ``` -#### 响应 +#### Response ```json { @@ -980,22 +980,22 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `metadata: optional Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: optional string or null` @@ -1005,7 +1005,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ - `VectorStore object { id, created_at, file_counts, 8 more }` - 向量存储是已处理文件的集合，可被 `file_search` 工具使用。 + 向量存储是已处理文件的集合，可供 `file_search` 工具使用。 - `id: string` @@ -1013,42 +1013,42 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ - `created_at: number` - 创建向量存储时的 Unix 时间戳（秒）。 + 向量存储创建时的 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` - `cancelled: number` - 已取消的文件数。 + 已取消的文件数量。 - `completed: number` - 已成功处理的文件数。 + 已成功处理的文件的数量。 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `last_active_at: number or null` - 向量存储上次活跃时的 Unix 时间戳（秒）。 + 向量存储最后活跃时的 Unix 时间戳（以秒为单位）。 - `metadata: Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: string` @@ -1062,7 +1062,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ - `status: "expired" or "in_progress" or "completed"` - 向量存储的状态，可以是 `expired`, `in_progress`，或 `completed`。状态为 `completed` 表示向量存储已准备好使用。 + 向量存储的状态，可以是 `expired`, `in_progress`，或者 `completed`。状态为 `completed` 表示向量存储已准备好使用。 - `"expired"` @@ -1080,17 +1080,17 @@ https://api.openai.com/v1/vector_stores/vs_abc123/search \ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `expires_at: optional number or null` - 向量存储过期时的 Unix 时间戳（秒）。 + 向量存储过期时的 Unix 时间戳（以秒为单位）。 ### 示例 @@ -1102,7 +1102,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \ -d '{}' ``` -#### 响应 +#### Response ```json { @@ -1143,7 +1143,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ }' ``` -#### 响应 +#### Response ```json { @@ -1163,13 +1163,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ } ``` -## 领域类型 +## Domain Types -### 自动文件分块策略参数 +### Auto File Chunking Strategy Param - `AutoFileChunkingStrategyParam object { type }` - 默认策略。此策略目前使用 `max_chunk_size_tokens` 和 `800` 。 `chunk_overlap_tokens` 和 `400`. + 默认策略。该策略当前使用 `max_chunk_size_tokens` 为 `800` 和 `chunk_overlap_tokens` 为 `400`. - `type: "auto"` @@ -1177,15 +1177,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `"auto"` -### 文件分块策略参数 +### File Chunking Strategy Param - `FileChunkingStrategyParam = AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam` - 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。 + 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` strategy。 - `AutoFileChunkingStrategyParam object { type }` - 默认策略。此策略目前使用 `max_chunk_size_tokens` 和 `800` 。 `chunk_overlap_tokens` 和 `400`. + 默认策略。该策略当前使用 `max_chunk_size_tokens` 为 `800` 和 `chunk_overlap_tokens` 为 `400`. - `type: "auto"` @@ -1201,13 +1201,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1219,7 +1219,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -1233,13 +1233,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. ### 静态文件分块策略对象 @@ -1249,13 +1249,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1273,13 +1273,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1291,7 +1291,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `VectorStore object { id, created_at, file_counts, 8 more }` - 向量存储是已处理文件的集合，可被 `file_search` 工具使用。 + 向量存储是已处理文件的集合，可供 `file_search` 工具使用。 - `id: string` @@ -1299,42 +1299,42 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `created_at: number` - 创建向量存储时的 Unix 时间戳（秒）。 + 向量存储创建时的 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` - `cancelled: number` - 已取消的文件数。 + 已取消的文件数量。 - `completed: number` - 已成功处理的文件数。 + 已成功处理的文件的数量。 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `last_active_at: number or null` - 向量存储上次活跃时的 Unix 时间戳（秒）。 + 向量存储最后活跃时的 Unix 时间戳（以秒为单位）。 - `metadata: Metadata or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + API 或控制台查询对象。 - 键是字符串，最大长度为 64 个字符。值是字符串 - ，最大长度为 512 个字符。 + 键为字符串，最长 64 个字符。值为字符串， + 最长 512 个字符。 - `name: string` @@ -1348,7 +1348,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `status: "expired" or "in_progress" or "completed"` - 向量存储的状态，可以是 `expired`, `in_progress`，或 `completed`。状态为 `completed` 表示向量存储已准备好使用。 + 向量存储的状态，可以是 `expired`, `in_progress`，或者 `completed`。状态为 `completed` 表示向量存储已准备好使用。 - `"expired"` @@ -1366,17 +1366,17 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `anchor: "last_active_at"` - 过期策略适用的锚定时间戳。支持的锚定： `last_active_at`. + 应用过期策略的锚定时间戳。支持的锚点： `last_active_at`. - `"last_active_at"` - `days: number` - 锚定时间之后向量存储将过期的天数。 + 在锚定时间之后向量存储将过期的天数。 - `expires_at: optional number or null` - 向量存储过期时的 Unix 时间戳（秒）。 + 向量存储过期时的 Unix 时间戳（以秒为单位）。 ### 向量存储已删除 @@ -1396,11 +1396,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `attributes: map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -1410,11 +1410,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `content: array of object { text, type }` - 来自文件的内容块。 + 来自文件的内容分块。 - `text: string` - 从搜索中返回的文本内容。 + 从搜索返回的文本内容。 - `type: "text"` @@ -1432,7 +1432,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `score: number` - 结果的相似性得分。 + 该结果的相似度评分。 # 文件批次 @@ -1440,7 +1440,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ **post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel` -取消向量存储文件批次。这将尝试尽快取消此批次中文件的处理。 +取消一个向量存储文件批次。此操作会尽快尝试取消该批次中文件的处理。 ### 路径参数 @@ -1452,7 +1452,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `VectorStoreFileBatch object { id, created_at, file_counts, 3 more }` - 一批附加到向量存储的文件。 + 附加到向量存储的一批文件。 - `id: string` @@ -1460,7 +1460,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `created_at: number` - 向量存储文件批次创建时的 Unix 时间戳（以秒为单位）。 + 向量存储文件批次的创建 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` @@ -1474,15 +1474,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `object: "vector_store.files_batch"` @@ -1504,7 +1504,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 ### 示例 @@ -1515,7 +1515,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATC -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -1544,7 +1544,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 -X POST ``` -#### 响应 +#### Response ```json { @@ -1577,11 +1577,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -1591,11 +1591,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `chunking_strategy: optional FileChunkingStrategyParam` - 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。 + 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` strategy。 - `AutoFileChunkingStrategyParam object { type }` - 默认策略。此策略目前使用 `max_chunk_size_tokens` 和 `800` 。 `chunk_overlap_tokens` 和 `400`. + 默认策略。该策略当前使用 `max_chunk_size_tokens` 为 `800` 和 `chunk_overlap_tokens` 为 `400`. - `type: "auto"` @@ -1611,13 +1611,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1627,23 +1627,23 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `file_ids: optional array of string` - 向量存储应使用的 [文件](/docs/api-reference/files) ID 列表。对诸如 `file_search` 可访问文件的工具。如果 `attributes` 或 `chunking_strategy` 被提供，它们将应用于批次中的所有文件。最大文件批次大小为 2000 个文件。此端点推荐用于多文件引入，有助于减少每个向量存储的写入请求压力。与 `files`. + 一个 [File](/docs/api-reference/files) 的 ID 列表，向量存储应使用这些 ID。可用于诸如 `file_search` 可用于访问文件。如果 `attributes` 或 `chunking_strategy` 已提供，它们将应用于批次中的所有文件。最大批次大小为 2000 个文件。建议将此端点用于多文件导入，有助于降低每个向量存储的写入请求压力。与 `files`. - `files: optional array of object { file_id, attributes, chunking_strategy }` - 对象列表，每个对象包含一个 `file_id` 以及可选的 `attributes` 或 `chunking_strategy`。当需要覆盖特定文件的元数据时使用。全局 `attributes` 或 `chunking_strategy` 将被忽略，必须为每个文件指定。最大文件批次大小为 2000 个文件。此端点推荐用于多文件引入，有助于减少每个向量存储的写入请求压力。与 `file_ids`. + 一个对象列表，每个对象都包含一个 `file_id` 以及可选的 `attributes` 或 `chunking_strategy`。当你需要为特定文件覆盖元数据时，请使用此选项。全局 `attributes` 或 `chunking_strategy` 将被忽略，并且必须为每个文件单独指定。最大批次大小为 2000 个文件。建议将此端点用于多文件导入，有助于降低每个向量存储的写入请求压力。与 `file_ids`. - `file_id: string` - 一个 [文件](/docs/api-reference/files) ID，向量存储应使用该 ID。适用于工具，如 `file_search` 可访问文件的工具。对于多文件引入，我们推荐 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以最小化每个向量存储的写入请求。 + 一个 [File](/docs/api-reference/files) 向量存储应使用的 ID。适用于类似 `file_search` 等可访问文件的工具。对于多文件导入，我们推荐 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以最大程度减少每个向量存储的写入请求。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -1653,13 +1653,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `chunking_strategy: optional FileChunkingStrategyParam` - 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。 + 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` strategy。 ### 返回 - `VectorStoreFileBatch object { id, created_at, file_counts, 3 more }` - 一批附加到向量存储的文件。 + 附加到向量存储的一批文件。 - `id: string` @@ -1667,7 +1667,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `created_at: number` - 向量存储文件批次创建时的 Unix 时间戳（以秒为单位）。 + 向量存储文件批次的创建 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` @@ -1681,15 +1681,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `object: "vector_store.files_batch"` @@ -1711,7 +1711,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 ### 示例 @@ -1723,7 +1723,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches \ -d '{}' ``` -#### 响应 +#### Response ```json { @@ -1767,7 +1767,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ }' ``` -#### 响应 +#### Response ```json { @@ -1790,7 +1790,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ **get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files` -返回批次中的向量存储文件列表。 +返回批处理中的向量存储文件列表。 ### 路径参数 @@ -1802,15 +1802,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo，以获取列表的下一页。 + 用于分页游标的对象 ID。 `after` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么后续调用可以包含 after=obj_foo，以便获取列表的下一页。 - `before: optional string` - 用于分页的游标。 `before` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 开头，那么你的后续调用可以包含 before=obj_foo，以获取列表的上一页。 + 用于分页游标的对象 ID。 `before` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 开头，那么后续调用可以包含 before=obj_foo，以便获取列表的上一页。 - `filter: optional "in_progress" or "completed" or "failed" or "cancelled"` - 按文件状态筛选。取值为 `in_progress`, `completed`, `failed`, `cancelled`. + 按文件状态筛选。可选值为以下之一 `in_progress`, `completed`, `failed`, `cancelled`. - `"in_progress"` @@ -1822,11 +1822,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `limit: optional number` - 对返回对象数量的限制。限制范围在 1 到 100 之间，默认为 20。 + 要返回的对象数量的上限。Limit 取值范围在 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` - 按对象的 `created_at` 时间戳排序。 `asc` 用于升序， `desc` 用于降序。 + 按对象的 `created_at` 时间戳排序。 `asc` 表示升序， `desc` 表示降序。 - `"asc"` @@ -1842,15 +1842,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -1860,7 +1860,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -1870,7 +1870,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -1882,19 +1882,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -1904,7 +1904,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -1912,13 +1912,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1928,7 +1928,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -1952,7 +1952,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATC -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -1996,7 +1996,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -2021,11 +2021,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 } ``` -## 检索向量存储文件批次 +## 检索向量存储文件批量 **get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}` -检索向量存储文件批次。 +检索一个向量存储文件批次。 ### 路径参数 @@ -2037,7 +2037,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `VectorStoreFileBatch object { id, created_at, file_counts, 3 more }` - 一批附加到向量存储的文件。 + 附加到向量存储的一批文件。 - `id: string` @@ -2045,7 +2045,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `created_at: number` - 向量存储文件批次创建时的 Unix 时间戳（以秒为单位）。 + 向量存储文件批次的创建 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` @@ -2059,15 +2059,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `object: "vector_store.files_batch"` @@ -2089,7 +2089,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 ### 示例 @@ -2099,7 +2099,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATC -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2127,7 +2127,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -2146,13 +2146,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 } ``` -## 领域类型 +## Domain Types ### 向量存储文件批次 - `VectorStoreFileBatch object { id, created_at, file_counts, 3 more }` - 一批附加到向量存储的文件。 + 附加到向量存储的一批文件。 - `id: string` @@ -2160,7 +2160,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 - `created_at: number` - 向量存储文件批次创建时的 Unix 时间戳（以秒为单位）。 + 向量存储文件批次的创建 Unix 时间戳（以秒为单位）。 - `file_counts: object { cancelled, completed, failed, 2 more }` @@ -2174,15 +2174,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 - `failed: number` - 处理失败的文件数。 + 处理失败的文件的数量。 - `in_progress: number` - 当前正在处理的文件数。 + 当前正在处理的文件的数量。 - `total: number` - 文件总数。 + 文件的总数。 - `object: "vector_store.files_batch"` @@ -2204,11 +2204,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 # 文件 -## 检索向量存储文件内容 +## 获取向量存储文件内容 **get** `/vector_stores/{vector_store_id}/files/{file_id}/content` @@ -2236,11 +2236,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 - `has_more: boolean` - 指示是否有更多内容页需要获取。 + 指示是否还有更多内容页可获取。 - `next_page: string or null` - 下一页的令牌（如有）。 + 下一页的令牌（若有）。 - `object: "vector_store.file_content.page"` @@ -2256,7 +2256,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID/con -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2280,7 +2280,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2294,11 +2294,11 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ } ``` -## 创建向量存储文件 +## Create vector store file **post** `/vector_stores/{vector_store_id}/files` -通过将 [File](/docs/api-reference/files) 附加到 [vector store](/docs/api-reference/vector-stores/object). +通过附加 [文件](/docs/api-reference/files) 到 [向量存储](/docs/api-reference/vector-stores/object). ### 路径参数 @@ -2308,15 +2308,15 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `file_id: string` - 一个 [文件](/docs/api-reference/files) ID，向量存储应使用该 ID。适用于工具，如 `file_search` 可访问文件的工具。对于多文件引入，我们推荐 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以最小化每个向量存储的写入请求。 + 一个 [File](/docs/api-reference/files) 向量存储应使用的 ID。适用于类似 `file_search` 等可访问文件的工具。对于多文件导入，我们推荐 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以最大程度减少每个向量存储的写入请求。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -2326,11 +2326,11 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `chunking_strategy: optional FileChunkingStrategyParam` - 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` 策略。 + 用于对文件进行分块的分块策略。如果未设置，将使用 `auto` strategy。 - `AutoFileChunkingStrategyParam object { type }` - 默认策略。此策略目前使用 `max_chunk_size_tokens` 和 `800` 。 `chunk_overlap_tokens` 和 `400`. + 默认策略。该策略当前使用 `max_chunk_size_tokens` 为 `800` 和 `chunk_overlap_tokens` 为 `400`. - `type: "auto"` @@ -2346,13 +2346,13 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -2372,15 +2372,15 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -2390,7 +2390,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -2400,7 +2400,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -2412,19 +2412,19 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -2434,7 +2434,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -2442,13 +2442,13 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -2458,7 +2458,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -2478,7 +2478,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files \ }' ``` -#### 响应 +#### Response ```json { @@ -2517,7 +2517,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ }' ``` -#### 响应 +#### Response ```json { @@ -2533,9 +2533,9 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ ## 删除向量存储文件 -**删除** `/vector_stores/{vector_store_id}/files/{file_id}` +**delete** `/vector_stores/{vector_store_id}/files/{file_id}` -删除一个向量存储文件。此操作会将该文件从向量存储中移除，但文件本身不会被删除。要删除文件，请使用 [delete file](/docs/api-reference/files/delete) 端点。 +删除一个向量存储文件。这将从向量存储中移除该文件，但文件本身不会被删除。若要删除该文件，请使用 [delete file](/docs/api-reference/files/delete) 端点。 ### 路径参数 @@ -2564,7 +2564,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2584,7 +2584,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ -X DELETE ``` -#### 响应 +#### Response ```json { @@ -2598,7 +2598,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ **get** `/vector_stores/{vector_store_id}/files` -返回向量存储文件的列表。 +返回向量存储文件列表。 ### 路径参数 @@ -2608,15 +2608,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo，以获取列表的下一页。 + 用于分页游标的对象 ID。 `after` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么后续调用可以包含 after=obj_foo，以便获取列表的下一页。 - `before: optional string` - 用于分页的游标。 `before` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 开头，那么你的后续调用可以包含 before=obj_foo，以获取列表的上一页。 + 用于分页游标的对象 ID。 `before` 是一个对象 ID，用于指定你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 开头，那么后续调用可以包含 before=obj_foo，以便获取列表的上一页。 - `filter: optional "in_progress" or "completed" or "failed" or "cancelled"` - 按文件状态筛选。取值为 `in_progress`, `completed`, `failed`, `cancelled`. + 按文件状态筛选。可选值为以下之一 `in_progress`, `completed`, `failed`, `cancelled`. - `"in_progress"` @@ -2628,11 +2628,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `limit: optional number` - 对返回对象数量的限制。限制范围在 1 到 100 之间，默认为 20。 + 要返回的对象数量的上限。Limit 取值范围在 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` - 按对象的 `created_at` 时间戳排序。 `asc` 用于升序， `desc` 用于降序。 + 按对象的 `created_at` 时间戳排序。 `asc` 表示升序， `desc` 表示降序。 - `"asc"` @@ -2648,15 +2648,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -2666,7 +2666,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -2676,7 +2676,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -2688,19 +2688,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -2710,7 +2710,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -2718,13 +2718,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -2734,7 +2734,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -2758,7 +2758,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2802,7 +2802,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -2831,7 +2831,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ **get** `/vector_stores/{vector_store_id}/files/{file_id}` -检索一个向量存储文件。 +检索向量存储文件。 ### 路径参数 @@ -2851,15 +2851,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -2869,7 +2869,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -2879,7 +2879,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -2891,19 +2891,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -2913,7 +2913,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -2921,13 +2921,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -2937,7 +2937,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -2953,7 +2953,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -#### 响应 +#### Response ```json { @@ -2989,7 +2989,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ -H "OpenAI-Beta: assistants=v2" ``` -#### 响应 +#### Response ```json { @@ -3018,11 +3018,11 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `attributes: map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -3042,15 +3042,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -3060,7 +3060,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -3070,7 +3070,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -3082,19 +3082,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -3104,7 +3104,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -3112,13 +3112,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -3128,7 +3128,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` @@ -3150,7 +3150,7 @@ curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \ }' ``` -#### 响应 +#### Response ```json { @@ -3186,7 +3186,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ -d '{"attributes": {"key1": "value1", "key2": 2}}' ``` -#### 响应 +#### Response ```json { @@ -3202,7 +3202,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ } ``` -## 领域类型 +## Domain Types ### 文件内容响应 @@ -3228,15 +3228,15 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `created_at: number` - 向量存储文件创建时的 Unix 时间戳（秒）。 + 该向量存储文件创建时的 Unix 时间戳（单位为秒）。 - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。若无错误，则为 `null` 。 + 与此向量存储文件关联的最近错误。如果无错误则将返回 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` - 取值为 `server_error`, `unsupported_file`，或 `invalid_file`. + 以下之一： `server_error`, `unsupported_file`，或者 `invalid_file`. - `"server_error"` @@ -3246,7 +3246,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `message: string` - 错误的人类可读描述。 + 该错误的人类可读描述。 - `object: "vector_store.file"` @@ -3256,7 +3256,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示该向量存储文件已可供使用。 + 向量存储文件的状态，可为 `in_progress`, `completed`, `cancelled`，或者 `failed`。之一。状态 `completed` 表示该向量存储文件已可使用。 - `"in_progress"` @@ -3268,19 +3268,19 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `usage_bytes: number` - 向量存储的总用量（字节）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 该 [vector store](/docs/api-reference/vector-stores/object) 所属 [文件](/docs/api-reference/files) 的ID。 + 所附加到的 [向量存储](/docs/api-reference/vector-stores/object) 的 ID。 [File](/docs/api-reference/files) 。 - `attributes: optional map[string or number or boolean] or null` - 一组 16 个键值对，可附加到对象上。这可以 - 用于以结构化格式存储关于对象的额外信息， - 格式，以及通过API或仪表盘查询对象。键是字符串 - ，最大长度为 64 个字符。值是字符串，最大 - 长度为 512 个字符、布尔值或数字。 + 可附加到对象的 16 个键值对。可用于 + 以结构化格式存储有关对象的附加信息，并通过 + 格式以及通过 API 或控制台查询对象。键为字符串 + ，最大长度为 64 个字符；值为最大长度为 512 个字符的字符串、布尔值或数值。 + length of 512 characters, booleans, or numbers. - `string` @@ -3290,7 +3290,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject` - 用于对文件进行分块的策略。 + 用于对文件进行分块（chunking）的策略。 - `StaticFileChunkingStrategyObject object { static, type }` @@ -3298,13 +3298,13 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `chunk_overlap_tokens: number` - 分块之间重叠的令牌数量。默认值为 `400`. + 块之间重叠的 token 数量。默认值为 `400`. - 请注意，重叠部分不得超过 `max_chunk_size_tokens`. + 注意重叠不能超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 的一半。每个分块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个块中最大的 token 数量。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -3314,7 +3314,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常，这是因为文件是在 `chunking_strategy` API引入该概念之前被索引的。 + 当分块策略未知时会返回此错误。通常是因为文件在引入该概念之前已建立索引， `chunking_strategy` 而该概念是在 API 中引入的。 - `type: "other"` diff --git a/docs/zh/api/reference/resources/vector_stores/subresources/files.md b/docs/zh/api/reference/resources/vector_stores/subresources/files.md index c8151a7..fadae60 100644 --- a/docs/zh/api/reference/resources/vector_stores/subresources/files.md +++ b/docs/zh/api/reference/resources/vector_stores/subresources/files.md @@ -1,12 +1,12 @@ -# 文件 +# Files -> 有关完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后附加 `.md` 获取。 +> 如需查看完整文档索引，请参阅 [llms.txt](/llms.txt)。在页面 URL 末尾添加 `.md` 即可获取文档页面的 Markdown 版本。 ## 检索向量存储文件内容 **get** `/vector_stores/{vector_store_id}/files/{file_id}/content` -获取向量存储文件的解析内容。 +检索向量存储文件的已解析内容。 ### 路径参数 @@ -18,7 +18,7 @@ - `data: array of object { text, type }` - 文件的解析内容。 + 文件的已解析内容。 - `text: optional string` @@ -34,7 +34,7 @@ - `next_page: string or null` - 下一页的令牌（如有）。 + 下一页的令牌（如果有）。 - `object: "vector_store.file_content.page"` @@ -92,25 +92,25 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ **post** `/vector_stores/{vector_store_id}/files` -通过附加 [文件](/docs/api-reference/files) 到 [向量存储](/docs/api-reference/vector-stores/object). +通过将一个 [File](/docs/api-reference/files) 附加到 [vector store](/docs/api-reference/vector-stores/object). ### 路径参数 - `vector_store_id: string` -### 请求体参数 +### Body 参数 - `file_id: string` - 一个 [文件](/docs/api-reference/files) 向量存储应使用的 ID。适用于能够访问文件的工具， `file_search` 对于多文件导入，我们建议使用 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以最小化每个向量存储的写入请求。 + 一个 [File](/docs/api-reference/files) 向量存储应使用的 ID。适用于 `file_search` 这类可以访问文件的工具。对于多文件导入，建议 [`file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch) 以减少每个向量存储的写入请求次数。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -134,19 +134,19 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `StaticFileChunkingStrategyObjectParam object { static, type }` - 通过设置块大小和块重叠来自定义你自己的分块策略。 + 通过设置分块大小和分块重叠来自定义你的分块策略。 - `static: StaticFileChunkingStrategy` - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -162,7 +162,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `id: string` - 标识符，可在 API 端点中引用。 + 该标识符，可在 API 端点中引用。 - `created_at: number` @@ -170,7 +170,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。如果没有错误，将为 `null` 。 + 与此向量存储文件关联的最后一个错误。如果没有错误则为 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` @@ -184,7 +184,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `message: string` - 错误的人类可读描述。 + 人类可读的错误描述。 - `object: "vector_store.file"` @@ -194,7 +194,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。该状态 `completed` 表示向量存储文件已准备好使用。 + 向量存储文件的状态，可能为 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示向量存储文件已可供使用。 - `"in_progress"` @@ -206,19 +206,19 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `usage_bytes: number` - 向量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 向量存储的 ID， [向量存储](/docs/api-reference/vector-stores/object) 该文件 [文件](/docs/api-reference/files) 附加到其上。 + 所附加的 [向量存储](/docs/api-reference/vector-stores/object) 的 [File](/docs/api-reference/files) 的 ID。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -236,13 +236,13 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -252,7 +252,7 @@ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常这是因为文件是在 `chunking_strategy` 概念是在 API 中引入的。 + 当分块策略未知时返回此值。通常，这是由于该文件在 `chunking_strategy` 该概念在 API 中引入。 - `type: "other"` @@ -327,9 +327,9 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ ## 删除向量存储文件 -**删除** `/vector_stores/{vector_store_id}/files/{file_id}` +**delete** `/vector_stores/{vector_store_id}/files/{file_id}` -删除向量存储文件。这会将该文件从向量存储中移除，但文件本身不会被删除。要删除文件，请使用 [删除文件](/docs/api-reference/files/delete) 端点。 +删除某个向量存储文件。这会从向量存储中移除该文件，但文件本身不会被删除。如需删除文件，请使用 [delete file](/docs/api-reference/files/delete) 接口。 ### 路径参数 @@ -392,25 +392,25 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ **get** `/vector_stores/{vector_store_id}/files` -返回向量存储文件列表。 +返回向量存储文件的列表。 ### 路径参数 - `vector_store_id: string` -### 查询参数 +### Query Parameters - `after: optional string` - 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 结尾，则后续调用可以包含 after=obj_foo 以获取列表的下一页。 + 用于分页的游标。 `after` 是一个对象 ID，用于定义你在列表中所处的位置。例如，如果你发起列表请求并收到 100 个对象，以 obj_foo 结尾，则后续调用可以包含 after=obj_foo 以获取列表的下一页。 - `before: optional string` - 用于分页的游标。 `before` 是一个对象 ID，用于定义你在列表中的位置。例如，如果你发出列表请求并收到 100 个对象，以 obj_foo 开头，则后续调用可以包含 before=obj_foo 以获取列表的上一页。 + 用于分页的游标。 `before` 是一个对象 ID，用于定义你在列表中所处的位置。例如，如果你发起列表请求并收到 100 个对象，以 obj_foo 开头，则后续调用可以包含 before=obj_foo 以获取列表的上一页。 - `filter: optional "in_progress" or "completed" or "failed" or "cancelled"` - 按文件状态过滤。取值之一为 `in_progress`, `completed`, `failed`, `cancelled`. + 按文件状态过滤。可选值为 `in_progress`, `completed`, `failed`, `cancelled`. - `"in_progress"` @@ -422,7 +422,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `limit: optional number` - 要返回的对象数量上限。限制范围在 1 到 100 之间，默认值为 20。 + 要返回的对象数量上限。范围在 1 到 100 之间，默认为 20。 - `order: optional "asc" or "desc"` @@ -438,7 +438,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `id: string` - 标识符，可在 API 端点中引用。 + 该标识符，可在 API 端点中引用。 - `created_at: number` @@ -446,7 +446,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。如果没有错误，将为 `null` 。 + 与此向量存储文件关联的最后一个错误。如果没有错误则为 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` @@ -460,7 +460,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `message: string` - 错误的人类可读描述。 + 人类可读的错误描述。 - `object: "vector_store.file"` @@ -470,7 +470,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。该状态 `completed` 表示向量存储文件已准备好使用。 + 向量存储文件的状态，可能为 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示向量存储文件已可供使用。 - `"in_progress"` @@ -482,19 +482,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `usage_bytes: number` - 向量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 向量存储的 ID， [向量存储](/docs/api-reference/vector-stores/object) 该文件 [文件](/docs/api-reference/files) 附加到其上。 + 所附加的 [向量存储](/docs/api-reference/vector-stores/object) 的 [File](/docs/api-reference/files) 的 ID。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -512,13 +512,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -528,7 +528,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常这是因为文件是在 `chunking_strategy` 概念是在 API 中引入的。 + 当分块策略未知时返回此值。通常，这是由于该文件在 `chunking_strategy` 该概念在 API 中引入。 - `type: "other"` @@ -641,7 +641,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `id: string` - 标识符，可在 API 端点中引用。 + 该标识符，可在 API 端点中引用。 - `created_at: number` @@ -649,7 +649,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。如果没有错误，将为 `null` 。 + 与此向量存储文件关联的最后一个错误。如果没有错误则为 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` @@ -663,7 +663,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `message: string` - 错误的人类可读描述。 + 人类可读的错误描述。 - `object: "vector_store.file"` @@ -673,7 +673,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。该状态 `completed` 表示向量存储文件已准备好使用。 + 向量存储文件的状态，可能为 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示向量存储文件已可供使用。 - `"in_progress"` @@ -685,19 +685,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `usage_bytes: number` - 向量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 向量存储的 ID， [向量存储](/docs/api-reference/vector-stores/object) 该文件 [文件](/docs/api-reference/files) 附加到其上。 + 所附加的 [向量存储](/docs/api-reference/vector-stores/object) 的 [File](/docs/api-reference/files) 的 ID。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -715,13 +715,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -731,7 +731,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常这是因为文件是在 `chunking_strategy` 概念是在 API 中引入的。 + 当分块策略未知时返回此值。通常，这是由于该文件在 `chunking_strategy` 该概念在 API 中引入。 - `type: "other"` @@ -808,15 +808,15 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `file_id: string` -### 请求体参数 +### Body 参数 - `attributes: map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -832,7 +832,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `id: string` - 标识符，可在 API 端点中引用。 + 该标识符，可在 API 端点中引用。 - `created_at: number` @@ -840,7 +840,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。如果没有错误，将为 `null` 。 + 与此向量存储文件关联的最后一个错误。如果没有错误则为 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` @@ -854,7 +854,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `message: string` - 错误的人类可读描述。 + 人类可读的错误描述。 - `object: "vector_store.file"` @@ -864,7 +864,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。该状态 `completed` 表示向量存储文件已准备好使用。 + 向量存储文件的状态，可能为 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示向量存储文件已可供使用。 - `"in_progress"` @@ -876,19 +876,19 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `usage_bytes: number` - 向量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 向量存储的 ID， [向量存储](/docs/api-reference/vector-stores/object) 该文件 [文件](/docs/api-reference/files) 附加到其上。 + 所附加的 [向量存储](/docs/api-reference/vector-stores/object) 的 [File](/docs/api-reference/files) 的 ID。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -906,13 +906,13 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -922,7 +922,7 @@ curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常这是因为文件是在 `chunking_strategy` 概念是在 API 中引入的。 + 当分块策略未知时返回此值。通常，这是由于该文件在 `chunking_strategy` 该概念在 API 中引入。 - `type: "other"` @@ -996,9 +996,9 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ } ``` -## 域类型 +## Domain Types -### 文件内容响应 +### File Content Response - `FileContentResponse object { text, type }` @@ -1010,7 +1010,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ 内容类型（目前仅 `"text"`) -### 向量存储文件 +### Vector Store File - `VectorStoreFile object { id, created_at, last_error, 6 more }` @@ -1018,7 +1018,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `id: string` - 标识符，可在 API 端点中引用。 + 该标识符，可在 API 端点中引用。 - `created_at: number` @@ -1026,7 +1026,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `last_error: object { code, message } or null` - 与此向量存储文件关联的最后一个错误。如果没有错误，将为 `null` 。 + 与此向量存储文件关联的最后一个错误。如果没有错误则为 `null` 。 - `code: "server_error" or "unsupported_file" or "invalid_file"` @@ -1040,7 +1040,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `message: string` - 错误的人类可读描述。 + 人类可读的错误描述。 - `object: "vector_store.file"` @@ -1050,7 +1050,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `status: "in_progress" or "completed" or "cancelled" or "failed"` - 向量存储文件的状态，可以是 `in_progress`, `completed`, `cancelled`，或 `failed`。该状态 `completed` 表示向量存储文件已准备好使用。 + 向量存储文件的状态，可能为 `in_progress`, `completed`, `cancelled`，或 `failed`。状态 `completed` 表示向量存储文件已可供使用。 - `"in_progress"` @@ -1062,19 +1062,19 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `usage_bytes: number` - 向量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 + 向量存储的总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。 - `vector_store_id: string` - 向量存储的 ID， [向量存储](/docs/api-reference/vector-stores/object) 该文件 [文件](/docs/api-reference/files) 附加到其上。 + 所附加的 [向量存储](/docs/api-reference/vector-stores/object) 的 [File](/docs/api-reference/files) 的 ID。 - `attributes: optional map[string or number or boolean] or null` - 可附加到对象的一组 16 个键值对。这可以 - 用于以结构化格式存储关于对象的额外信息， - 并通过 API 或仪表板查询对象。键是字符串， - 最大长度为 64 个字符。值是最大 - 长度为 512 个字符的字符串、布尔值或数字。 + 可附加到对象的 16 个键值对集合。可用于 + 以结构化格式存储对象的附加信息，并通过 API 或控制台查询对象。键为字符串， + 最长 64 个字符。值为字符串，最长 + 512 个字符，也可以是布尔值或数字。 + 长度上限为 512 个字符，也可以是布尔值或数字。 - `string` @@ -1092,13 +1092,13 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `chunk_overlap_tokens: number` - 块之间重叠的令牌数。默认值为 `400`. + 分块之间重叠的 token 数。默认值为 `400`. - 请注意，重叠不得超过 `max_chunk_size_tokens`. + 注意重叠不得超过 `max_chunk_size_tokens`. - `max_chunk_size_tokens: number` - 每个块中的最大令牌数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. + 每个分块中的最大 token 数。默认值为 `800`。最小值为 `100` ，最大值为 `4096`. - `type: "static"` @@ -1108,7 +1108,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `OtherFileChunkingStrategyObject object { type }` - 当分块策略未知时返回此值。通常这是因为文件是在 `chunking_strategy` 概念是在 API 中引入的。 + 当分块策略未知时返回此值。通常，这是由于该文件在 `chunking_strategy` 该概念在 API 中引入。 - `type: "other"` @@ -1116,7 +1116,7 @@ curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ - `"other"` -### 向量存储文件已删除 +### Vector Store File Deleted - `VectorStoreFileDeleted object { id, deleted, object }` diff --git a/docs/zh/api/reference/resources/videos.md b/docs/zh/api/reference/resources/videos.md index ebd638b..f4a8f3a 100644 --- a/docs/zh/api/reference/resources/videos.md +++ b/docs/zh/api/reference/resources/videos.md @@ -1,14 +1,14 @@ -# 视频 +# Videos -> 有关完整的文档索引，请参阅 [llms.txt](/llms.txt)。文档页面的 Markdown 版本可通过在页面 URL 后追加 `.md` 获得。 +> 完整的文档索引请参阅 [llms.txt](/llms.txt)。可通过在页面 URL 后追加 `.md` 来获取文档页面的 Markdown 版本。 ## 创建视频 **post** `/videos` -根据提示词和可选的参考素材创建新的视频生成任务。 +根据提示词和可选的参考素材创建一个新的视频生成任务。 -### 请求体参数 +### 正文参数 - `prompt: string` @@ -16,17 +16,17 @@ - `input_reference: optional ImageInputReferenceParam` - 用于指导生成的可选参考对象。请提供且仅提供以下之一： `image_url` 或 `file_id`. + 用于引导生成的可选参考对象。只能提供以下之一 `image_url` 或 `file_id`. - `file_id: optional string` - `image_url: optional string` - 一个完全限定的 URL 或 base64 编码的数据 URL。 + 完整的 URL 或 base64 编码的 data URL。 - `model: optional VideoModel` - 用于视频生成的模型（允许值：sora-2、sora-2-pro）。默认为 `sora-2`. + 要使用的视频生成模型（允许的值：sora-2、sora-2-pro）。默认为 `sora-2`. - `string` @@ -44,7 +44,7 @@ - `seconds: optional VideoSeconds` - 片段时长（秒）（允许值：4、8、12）。默认为 4 秒。 + 片段时长（单位：秒，允许的值：4、8、12）。默认为 4 秒。 - `"4"` @@ -54,7 +54,7 @@ - `size: optional VideoSize` - 输出分辨率，格式为宽 x 高（允许值：720x1280、1280x720、1024x1792、1792x1024）。默认为 720x1280。 + 输出分辨率，格式为 宽 x 高（允许的值：720x1280、1280x720、1024x1792、1792x1024）。默认为 720x1280。 - `"720x1280"` @@ -64,11 +64,11 @@ - `"1792x1024"` -### 返回 +### Returns - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -76,7 +76,7 @@ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -84,7 +84,7 @@ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -92,11 +92,11 @@ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -128,19 +128,19 @@ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -152,7 +152,7 @@ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -225,17 +225,17 @@ curl https://api.openai.com/v1/videos \ **post** `/videos/characters` -从上传的视频创建角色。 +Create a character from an uploaded video. -### 返回 +### Returns - `id: string or null` - 角色创建客串的标识符。 + 角色创建 cameo 的标识符。 - `created_at: number` - 角色创建时的 Unix 时间戳（秒）。 + 角色创建时的 Unix 时间戳（以秒为单位）。 - `name: string or null` @@ -263,15 +263,15 @@ curl https://api.openai.com/v1/videos/characters \ ## 删除视频 -**删除** `/videos/{video_id}` +**delete** `/videos/{video_id}` -永久删除已完成或失败的视频及其存储的资产。 +永久删除已完成的或失败的视频及其存储的资源。 ### 路径参数 - `video_id: string` -### 返回 +### Returns - `id: string` @@ -279,11 +279,11 @@ curl https://api.openai.com/v1/videos/characters \ - `deleted: boolean` - 表示视频资源已被删除。 + 指示视频资源已被删除。 - `object: "video.deleted"` - 指示删除响应的对象类型。 + 表示删除响应的对象类型。 - `"video.deleted"` @@ -307,11 +307,11 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ ## 检索视频内容 -**获取** `/videos/{video_id}/content` +**get** `/videos/{video_id}/content` -下载生成的视频字节或派生预览资源。 +下载生成的视频字节或派生的预览资源。 -流式传输指定视频作业的渲染视频内容。 +为指定视频任务流式传输已渲染的视频内容。 ### 路径参数 @@ -321,7 +321,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `variant: optional "video" or "thumbnail" or "spritesheet"` - 要返回哪个可下载资源。默认为 MP4 视频。 + 要返回的可下载资源。默认为 MP4 视频。 - `"video"` @@ -336,13 +336,13 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` -## 通过编辑源视频或已生成的视频来创建新的视频生成任务。 +## 通过编辑源视频或现有的已生成视频，创建一个新的视频生成任务。 **post** `/videos/edits` -通过编辑源视频或已有的生成视频来创建新的视频生成任务。 +通过编辑源视频或已有生成视频来创建一个新的视频生成任务。 -### 请求体参数 +### 正文参数 - `prompt: string` @@ -350,17 +350,17 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `video: object { id }` - 对要编辑的已完成视频的引用。 + 指向已完成的待编辑视频的引用。 - `id: string` 已完成视频的标识符。 -### 返回 +### Returns - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -368,7 +368,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -376,7 +376,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -384,11 +384,11 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -420,19 +420,19 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -444,7 +444,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID/content \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -491,21 +491,21 @@ curl https://api.openai.com/v1/videos/edits \ } ``` -## 创建已完成视频的扩展。 +## Create an extension of a completed video. **post** `/videos/extensions` 创建已完成视频的扩展。 -### 请求体参数 +### 正文参数 - `prompt: string` - 更新后的文本提示，用于指导扩展生成。 + 用于指导扩展生成环节的更新后文本提示词。 - `seconds: VideoSeconds` - 新生成的扩展片段长度（秒）（允许值：4、8、12、16、20）。 + 新生成的扩展片段时长（单位为秒，允许的值：4、8、12、16、20）。 - `"4"` @@ -515,17 +515,17 @@ curl https://api.openai.com/v1/videos/edits \ - `video: object { id }` - 对要扩展的已完成视频的引用。 + 对已完成视频的引用，用于对其进行扩展。 - `id: string` 已完成视频的标识符。 -### 返回 +### Returns - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -533,7 +533,7 @@ curl https://api.openai.com/v1/videos/edits \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -541,7 +541,7 @@ curl https://api.openai.com/v1/videos/edits \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -549,11 +549,11 @@ curl https://api.openai.com/v1/videos/edits \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -585,19 +585,19 @@ curl https://api.openai.com/v1/videos/edits \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -609,7 +609,7 @@ curl https://api.openai.com/v1/videos/edits \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -659,7 +659,7 @@ curl https://api.openai.com/v1/videos/extensions \ ## 获取一个字符。 -**获取** `/videos/characters/{character_id}` +**get** `/videos/characters/{character_id}` 获取一个字符。 @@ -667,15 +667,15 @@ curl https://api.openai.com/v1/videos/extensions \ - `character_id: string` -### 返回 +### Returns - `id: string or null` - 角色创建客串的标识符。 + 角色创建 cameo 的标识符。 - `created_at: number` - 角色创建时的 Unix 时间戳（秒）。 + 角色创建时的 Unix 时间戳（以秒为单位）。 - `name: string or null` @@ -700,7 +700,7 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ ## 列出视频 -**获取** `/videos` +**get** `/videos` 列出当前项目最近生成的视频。 @@ -716,13 +716,13 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `order: optional "asc" or "desc"` - 按时间戳对结果进行排序。使用 `asc` 表示升序，或 `desc` 表示降序。 + 按时间戳对结果进行排序。使用 `asc` 表示升序，或使用 `desc` 表示降序。 - `"asc"` - `"desc"` -### 返回 +### Returns - `data: array of Video` @@ -734,7 +734,7 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -742,7 +742,7 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -750,11 +750,11 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -786,19 +786,19 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -810,7 +810,7 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -822,19 +822,19 @@ curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \ - `first_id: string or null` - 列表中第一个项目的 ID。 + 列表中第一项的 ID。 - `has_more: boolean` - 是否还有更多可用项目。 + 是否还有更多可用项。 - `last_id: string or null` - 列表中最后一个项目的 ID。 + 列表中最后一项的 ID。 - `object: "list"` - 返回的对象类型，必须是 `list`. + 返回对象的类型，必须为 `list`. - `"list"` @@ -899,27 +899,27 @@ curl https://api.openai.com/v1/videos \ } ``` -## Remix 视频 +## Remix video **post** `/videos/{video_id}/remix` -使用刷新后的提示词，为已完成的视频创建一个混剪版本。 +使用更新后的提示词创建已生成视频的混剪版本。 ### 路径参数 - `video_id: string` -### 请求体参数 +### 正文参数 - `prompt: string` - 用于指导混音生成的更新文本提示。 + 更新后的文本提示，用于引导 remix 生成。 -### 返回 +### Returns - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -927,7 +927,7 @@ curl https://api.openai.com/v1/videos \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -935,7 +935,7 @@ curl https://api.openai.com/v1/videos \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -943,11 +943,11 @@ curl https://api.openai.com/v1/videos \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -979,19 +979,19 @@ curl https://api.openai.com/v1/videos \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -1003,7 +1003,7 @@ curl https://api.openai.com/v1/videos \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -1076,19 +1076,19 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ ## 检索视频 -**获取** `/videos/{video_id}` +**get** `/videos/{video_id}` -获取已生成视频的最新元数据。 +获取所生成视频的最新元数据。 ### 路径参数 - `video_id: string` -### 返回 +### Returns - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -1096,7 +1096,7 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -1104,7 +1104,7 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -1112,11 +1112,11 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -1148,19 +1148,19 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -1172,7 +1172,7 @@ curl -X POST https://api.openai.com/v1/videos/video_123/remix \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -1212,9 +1212,9 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ } ``` -## 领域类型 +## 域类型 -### 图像输入参考参数 +### 图片输入参考参数 - `ImageInputReferenceParam object { file_id, image_url }` @@ -1222,13 +1222,13 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `image_url: optional string` - 一个完全限定的 URL 或 base64 编码的数据 URL。 + 完整的 URL 或 base64 编码的 data URL。 ### 视频 - `Video object { id, completed_at, created_at, 10 more }` - 描述所生成视频任务的结构化信息。 + 描述生成的视频任务的结构化信息。 - `id: string` @@ -1236,7 +1236,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `completed_at: number or null` - 任务完成时的 Unix 时间戳（秒），如果已结束。 + 任务完成时的 Unix 时间戳（秒），如果已完成。 - `created_at: number` @@ -1244,7 +1244,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `error: VideoCreateError or null` - 解释生成失败原因的错误负载，如果适用。 + 用于解释生成失败原因的错误负载（如适用）。 - `code: string` @@ -1252,11 +1252,11 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 - `expires_at: number or null` - 可下载资产过期时的 Unix 时间戳（秒），如果已设置。 + 可下载资源过期时的 Unix 时间戳（秒），如果已设置。 - `model: VideoModel` @@ -1288,19 +1288,19 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `prompt: string or null` - 用于生成视频的提示词。 + 用于生成该视频的提示词。 - `remixed_from_video_id: string or null` - 如果此视频是混剪，则为源视频的标识符。 + 如果该视频为二次创作，则为源视频的标识符。 - `seconds: string` - 生成剪辑的时长（秒）。对于扩展，这是拼接后的总时长。 + 生成片段的时长（秒）。对于扩展，这是拼接后的总时长。 - `size: VideoSize` - 生成视频的分辨率。 + 所生成视频的分辨率。 - `"720x1280"` @@ -1312,7 +1312,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `status: "queued" or "in_progress" or "completed" or "failed"` - 视频任务的当前生命周期状态。 + 视频任务当前的生命周期状态。 - `"queued"` @@ -1322,27 +1322,27 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `"failed"` -### 视频创建角色响应 +### Video Create Character 响应 - `VideoCreateCharacterResponse object { id, created_at, name }` - `id: string or null` - 角色创建客串的标识符。 + 角色创建 cameo 的标识符。 - `created_at: number` - 角色创建时的 Unix 时间戳（秒）。 + 角色创建时的 Unix 时间戳（以秒为单位）。 - `name: string or null` 角色的显示名称。 -### 视频创建错误 +### Video Create 错误 - `VideoCreateError object { code, message }` - 生成响应时发生的错误。 + 生成响应过程中发生的错误。 - `code: string` @@ -1350,9 +1350,9 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `message: string` - 返回的错误的可读描述。 + 返回错误的人类可读描述。 -### 视频删除响应 +### Video Delete Response - `VideoDeleteResponse object { id, deleted, object }` @@ -1364,31 +1364,31 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `deleted: boolean` - 表示视频资源已被删除。 + 指示视频资源已被删除。 - `object: "video.deleted"` - 指示删除响应的对象类型。 + 表示删除响应的对象类型。 - `"video.deleted"` -### 视频获取角色响应 +### Video Get Character Response - `VideoGetCharacterResponse object { id, created_at, name }` - `id: string or null` - 角色创建客串的标识符。 + 角色创建 cameo 的标识符。 - `created_at: number` - 角色创建时的 Unix 时间戳（秒）。 + 角色创建时的 Unix 时间戳（以秒为单位）。 - `name: string or null` 角色的显示名称。 -### 视频模型 +### Video Model - `VideoModel = string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` @@ -1406,7 +1406,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `"sora-2-2025-12-08"` -### 视频秒数 +### Video Seconds - `VideoSeconds = "4" or "8" or "12"` @@ -1416,7 +1416,7 @@ curl https://api.openai.com/v1/videos/$VIDEO_ID \ - `"12"` -### 视频大小 +### Video Size - `VideoSize = "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`